String Commands 


The string interface enables application control of media devices using textual string commands. String commands are passed to the media 
control interface through the mciSendString function. Return information from string commands is converted to string format and returned in 
the pszF/eturnStr/ng parameter of mciSendString. 

Not all functions available through the procedural interface, mciSendCommand, are available through the string interface. In general, 
operations that return complex data structures, such as a CD table of contents, are available only through the procedural interface. 
Operations that cause asynchronous responses to be generated, such as cue point and position advise, can be invoked from the string 
interface; however, their responses are returned to window procedures. 

The keywords WAIT and NOTIFY are global keywords and are available for all commands except some system commands. As with the 
procedural interface, the default time base is MMTIME. The multimedia string parser is case insensitive. 

Command Format 

The string format is: 

COMMAND object 

keywords WAIT 

NOTIFY 


where 


object 
keywords 
WAIT | NOTIFY 


= device type | device name | filename | alias 
= command-specific keywords 
= standard OS/2 multimedia definitions 


The object associated with a media control interface command can be one of the following: 


Device type - The default device of a given type. The possible types of controllable devices include the following: 


Device 

videotape 

videodisc 

cdaudio 

waveaudio 

sequencer 

digitalvideo 


Description 

Videotape player or recorder 
Videodisc player 

CD-ROM device that supports standard compact disc playback 
Device that supports digital audio files 
Device that supports MIDI files 

Device that supports audio/video files, either hardware-assisted or software 
motion video only 


If you have multiple devices of the same type, the Multimedia Setup program allows you to decide which device should be the 
default for that type. 

Device name - A name of a particular device. Device names are of the form Dev/cetypeA/AJ , where Dev/cetype is one of the 
device types given above, and A/A/ is a value (01 , 02,...) indicating which device of that type is to be controlled. 


Filename - The name of a file to be opened or controlled. When a filename is opened, OS/2 multimedia first examines the file's 
extension, then its type, to determine which device is associated to the file. 


Alias - A string that was specified on a previous OPEN command. This string can then be used as the object name in 
subsequent commands. 


The only exception to the above command format is MASTERAUDIO, which does not require an object associated with the command. The 
format for MASTERAUDIO is: 


MASTERAUDIO keywords 


WAIT 


How to Read the Syntax Diagram 


The syntax diagram shows you how to specify a command so that the multimedia string parser can correctly interpret what you type. Read 
the syntax diagram from left to right and from top to bottom, following the horizontal baseline (the main path). The command name and items 


required to make the command work appear on the baseline; the items below the baseline are optional. 

A line ending with an arrowhead means that the command syntax is continued. A line starting with an arrowhead means that the syntax is 
continued from the previous line. A vertical bar marks the end of the command syntax. 

Command names are often followed by required or optional keywords , which affect the result of the command. Variables are represented in 
lowercase and must be replaced with a valid name or value you specify. In the following example, object, devicealias, and devicetype are 
variables. You must include any punctuation, such as parentheses or commas, that are shown in the diagram. 

OPEN object 

ALIAS devicealias WAIT 

SHAREABLE NOTIFY 

TYPE devicetype 


In the OPEN command shown above, object is required, the ALIAS, SHAREABLE, and TYPE keywords are optional, and the WAIT and 
NOTIFY keywords are also optional. 


Specifying Items Once in Any Order 

A stack of keywords with a return arrow above the main path indicates that you can specify one or more keywords in any order, but you can 
specify each keyword only once. 


COPY object 


FROM pos 
TO pos 


WAIT 

NOTIFY 


Specifying One Item from a Stack 

A stack of keywords with no return arrow means that you cannot specify more than one keyword from the stack. 


SEEK 

object 

TO pos 
TO START 

WAIT 



TO END 

NOTIFY 


System Commands 


System commands are interpreted directly by the media device manager (MDM), and are not passed to media control interface drivers. The 
following commands are system commands: 

ACQUIRE 

• CONNECTION 
CONNECTORINFO 

• DEFAULTCONNECTION 
GROUP 

• MASTERAUDIO 
RELEASE 

• SYSINFO 


ACQUIRE 


ACQUIRE (System Command) - Example 


acquire digitalvideo exclusive wait 


ACQUIRE (System Command) - Purpose 


The ACQUIRE command acquires use of the physical resources for the device. The EXCLUSIVE and EXCLUSIVE INSTANCE keywords 
cannot be used together. 


ACQUIRE (System Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


ACQUIRE (System Command) Keyword - EXCLUSIVE 


EXCLUSIVE 

Acquires the physical resource for exclusive use. If the resource is not available, MCIERR_DEVICE_IN_USE is returned. Exclusive 
use of a device can be released with the RELEASE system command. 


ACQUIRE (System Command) Keyword - EXCLUSIVE 
INSTANCE 


EXCLUSIVE INSTANCE 

Acquires the device such that whether being used or not, it cannot be made inactive by another request. 


ACQUIRE (System Command) Keyword - QUEUE 


QUEUE 

Queues ACQUIRE command to be executed when device resources become available. 


ACQUIRE (System Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


ACQUIRE (System Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


ACQUIRE (System Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

EXCLUSIVE 

Acquires the physical resource for exclusive use. If the resource is not available, MCIERR_DEVICE_IN_USE is returned. Exclusive 
use of a device can be released with the RELEASE system command. 

EXCLUSIVE INSTANCE 

Acquires the device such that whether being used or not, it cannot be made inactive by another request. 

QUEUE 

Queues ACQUIRE command to be executed when device resources become available. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


ACQUIRE (System Command) - Syntax Diagram 


ACQUIRE 


object 


EXCLUSIVE 

EXCLUSIVE INSTANCE 


QUEUE 


WAIT 

NOTIFY 


Examples 


ACQUIRE (System Command) - Topics 
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CONNECTION 


CONNECTION (System Command) - Example 


open waveaudio alias wave shareable wait 


The following command returns the alias name of the connected device fampmix''). 

connection wave query type wave stream alias ampmix wait 


CONNECTION (System Command) - Purpose 


The CONNECTION command returns information about the device context connections. 


CONNECTION (System Command) Keyword - object 



object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CONNECTION (System Command) Keyword - QUERY 


QUERY 

Queries the connection as defined by the NUMBER and TYPE item. If a connection exists, the alias of the connected device is 
returned. If no alias is defined, then a null string is returned. If QUERY and ALIAS are both specified, then the specified alias name is 
returned and assigned, if possible. See the ALIAS keyword for more information on possible errors. 


CONNECTION (System Command) Keyword - NUMBER 
connector number 


NUMBER connector number 

Indicates the connector number to which this query applies. If this item is omitted, then the first connector is assumed. If the TYPE 
keyword is included, then the connector number is interpreted as a relative offset within the specified connector type. 

Note: This keyword is used in conjunction with the QUERY keyword. 


CONNECTION (System Command) Keyword - TYPE 
connector_type 

TYPE connector type 

The type of connector to which the requested action applies. The following connector types are defined: 

Note: This keyword is used in conjunction with the QUERY keyword. 

MIDI stream 

Digital input or output for a sequencer device. This data is typically streamed to an amplifier mixer device. 

CD stream 

Digital output for a CD audio device capable of reading the data directly off of a disk. The data is typically 
streamed to an amplifier mixer device. 

wave stream 

Digital input or output for a waveform audio device. The data is typically streamed to an amplifier mixer device. 

XA stream 

Digital output for a CD-ROM/XA device. The data is typically streamed to an amplifier mixer device. 



amp stream 
headphones 
speakers 
microphone 
line in 
line out 
video in 
video out 


Digital input or output for an amplifier mixer device. 

The connector on the device which is labeled or is typically used to attach headphones to the device. 

The connector on the device which is labeled or is typically used to attach speakers to the device. 

The connector on the device which is labeled or is typically used to attach a microphone to the device. 

The connector on the device which is labeled or is typically used to provide line level input to the device. 

The connector on the device which is labeled or is typically used to provide line level output from the device. 

The connector on the device which is labeled or is typically used to provide video input to the device. 

The connector on the device which is labeled or is typically used to provide video output from the device. 


CONNECTION (System Command) Keyword - ALIAS 
device alias 


ALIAS device_alias 

Defines an alias for the device connected to the specified connector. If the alias already exists for another device the error 
MCIERR_DUPLICATE_ALIAS is returned. If the device connected to already has an alias the error MCIERR_CANNOT_ADD_ALIAS 
is returned. 

Note: This keyword is used in conjunction with the QUERY keyword. 


CONNECTION (System Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CONNECTION (System Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTION (System Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

QUERY 

Queries the connection as defined by the NUMBER and TYPE item. If a connection exists, the alias of the connected device is 
returned. If no alias is defined, then a null string is returned. If QUERY and ALIAS are both specified, then the specified alias name is 
returned and assigned, if possible. See the ALIAS keyword for more information on possible errors. 

NUMBER connector number 

Indicates the connector number to which this query applies. If this item is omitted, then the first connector is assumed. If the TYPE 
keyword is included, then the connector number is interpreted as a relative offset within the specified connector type. 

Note: This keyword is used in conjunction with the QUERY keyword. 

TYPE connector type 

The type of connector to which the requested action applies. The following connector types are defined: 

Note: This keyword is used in conjunction with the QUERY keyword. 

MIDI stream 

Digital input or output for a sequencer device. This data is typically streamed to an amplifier mixer device. 

CD stream 

Digital output for a CD audio device capable of reading the data directly off of a disk. The data is typically 
streamed to an amplifier mixer device. 

wave stream 

Digital input or output for a waveform audio device. The data is typically streamed to an amplifier mixer device. 

XA stream 

Digital output for a CD-ROM/XA device. The data is typically streamed to an amplifier mixer device. 

amp stream 

Digital input or output for an amplifier mixer device. 

headphones 

The connector on the device which is labeled or is typically used to attach headphones to the device. 

speakers 

The connector on the device which is labeled or is typically used to attach speakers to the device. 

microphone 

The connector on the device which is labeled or is typically used to attach a microphone to the device. 

line in 

The connector on the device which is labeled or is typically used to provide line level input to the device. 

line out 

The connector on the device which is labeled or is typically used to provide line level output from the device. 

video in 

The connector on the device which is labeled or is typically used to provide video input to the device. 

video out 

The connector on the device which is labeled or is typically used to provide video output from the device. 

ALIAS device_alias 

Defines an alias for the device connected to the specified connector. If the alias already exists for another device the error 
MCIERR_DUPLICATE_ALIAS is returned. If the device connected to already has an alias the error MCIERR_CANNOT_ADD_ALIAS 
is returned. 

Note: This keyword is used in conjunction with the QUERY keyword. 

WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 



application. 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTION (System Command) - Syntax Diagram 


CONNECTION object 


QUERY 

NUMBER connector_number 
TYPE connector_type 
ALIAS device_alias 


WAIT 

NOTIFY 


Examples 
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CONNECTORINFO 


CONNECTORINFO (System Command) - Example 


The following command returns "wave stream". 


connectorinf o digitalvideo typeof number 1 wait 



CONNECTORINFO (System Command) - Purpose 


The CONNECTORINFO command returns information about the connectors on a device. 


CONNECTORINFO (System Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CONNECTORINFO (System Command) Keyword - 
ENUMERATE 


ENUMERATE 

Returns the number of connectors of the specified type. If no TYPE keyword is specified, then the total number of connectors for the 
device is returned. 


CONNECTORINFO (System Command) Keyword - TYPE 
connector_type 


TYPE connector type 

Indicates the type of connector to which the query applies. The connector types are defined for each device. See the TYPE keyword 
for CONNECTION for a list of supported connector types. 


CONNECTORINFO (System Command) Keyword - TYPEOF 


TYPEOF 

Returns the connector type of the specified connector. Use of this option requires that the NUMBER keyword must also be specified. 


CONNECTORINFO (System Command) Keyword - NUMBER 


connector number 


NUMBER connectornumber 

Indicates the connector number to which this query applies. 


CONNECTORINFO (System Command) Keyword - CAN 
CONNECT TO connector type 


CAN CONNECT TO connector type 

Returns true if this connector type is compatible with the connector type of the specified connector; that is, results in a valid 
connection. Use of this option requires that the TYPE keyword must also be specified. 


CONNECTORINFO (System Command) Keyword - TYPE 
connector_type 

TYPE connector type 

Indicates the type of connector to which the query applies. The connector types are defined for each device. See the TYPE keyword 
for CONNECTION for a list of supported connector types. 


CONNECTORINFO (System Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified to receive return string information. 


CONNECTORINFO (System Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTORINFO (System Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 

ENUMERATE 

Returns the number of connectors of the specified type. If no TYPE keyword is specified, then the total number of connectors for the 
device is returned. 

TYPE connectortype 

Indicates the type of connector to which the query applies. The connector types are defined for each device. See 
the TYPE keyword for CONNECTION for a list of supported connector types. 


TYPEOF 

Returns the connector type of the specified connector. Use of this option requires that the NUMBER keyword must also be specified. 

NUMBER connectornumber 

Indicates the connector number to which this query applies. 

CAN CONNECT TO connector type 

Returns true if this connector type is compatible with the connector type of the specified connector; that is, results in a valid 
connection. Use of this option requires that the TYPE keyword must also be specified. 

TYPE connector type 

Indicates the type of connector to which the query applies. The connector types are defined for each device. See 
the TYPE keyword for CONNECTION for a list of supported connector types. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


CONNECTORINFO (System Command) - Syntax Diagram 


CONNECTORINFO object 


ENUMERATE 

TYPE connector_type 
TYPEOF NUMBER connector_number 

CAN CONNECT TO connector_type TYPE connector_type 


WAIT 

NOTIFY 


Examples 


CONNECTORINFO (System Command) - Topics 
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DEFAULTCONNECTION 


DEFAULTCONNECTION (System Command) - Example 


The following command returns "ampmixOI ampmix 1" 

default connect ion digitalvideo query wait 


DEFAULTCONNECTION (System Command) - Purpose 


The DEFAULTCONNECTION command makes, breaks, or queries a default connection. 


DEFAULTCONNECTION (System Command) Keyword - 
object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


DEFAULTCONNECTION (System Command) Keyword - 
MAKE TO devicename 


MAKE TO devicename 

Establish a connection. The devicename is necessary for connection to be established. Use of the MAKE TO keyword also requires 


the TONUMBER and/or TOTYPE keyword. 


DEFAULTCONNECTION (System Command) Keyword - 
TYPE connector type 


TYPE connector type 

Indicates the connector type. 


DEFAULTCONNECTION (System Command) Keyword - 
NUMBER connector number 


NUMBER connectornumber 

Indicates the connector number to which the action applies. If this item is omitted, then the first connector is assumed. If the TYPE 
keyword is included, then the connector number is interpreted as a relative offset within the specified connector type. 


DEFAULTCONNECTION (System Command) Keyword - 
TOTYPE connector type 


TOTYPE connector type 

Indicates the type of connector on the target device. 


DEFAULTCONNECTION (System Command) Keyword - 
TONUMBER connector number 


TONUMBER connector number 

Indicates the connector number on the target device during a MAKE action. If this item is omitted, the first connector is assumed. If 
the TOTYPE keyword is included, then the connector number is interpreted as a relative offset within the specified connector type. 


DEFAULTCONNECTION (System Command) Keyword - 
BREAK 



BREAK 

Delete a connection. If the BREAK keyword is specified, the TYPE keyword is also required. 


DEFAULTCONNECTION (System Command) Keyword - 
TYPE connector type 


TYPE connector type 

Indicates the connector type. 


DEFAULTCONNECTION (System Command) Keyword - 
QUERY 


QUERY 

Query a connection. Returns the devicename, connector_type, and connector_number. 


DEFAULTCONNECTION (System Command) Keyword - 
WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT flag must be specified to receive return string information. 


DEFAULTCONNECTION (System Command) Keyword - 
NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


DEFAULTCONNECTION (System Command) - Keywords 


object 


Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

MAKE TO devicename 

Establish a connection. The devicename is necessary for connection to be established. Use of the MAKE TO keyword also requires 
the TONUMBER and/or TOTYPE keyword. 

TYPE connectortype 

Indicates the connector type. 

NUMBER connectornumber 

Indicates the connector number to which the action applies. If this item is omitted, then the first connector is 
assumed. If the TYPE keyword is included, then the connector number is interpreted as a relative offset within the 
specified connector type. 

TOTYPE connector type 

Indicates the type of connector on the target device. 

TONUMBER connector number 

Indicates the connector number on the target device during a MAKE action. If this item is omitted, the first 
connector is assumed. If the TOTYPE keyword is included, then the connector number is interpreted as a relative 
offset within the specified connector type. 


BREAK 

Delete a connection. If the BREAK keyword is specified, the TYPE keyword is also required. 

TYPE connector type 

Indicates the connector type. 


QUERY 

Query a connection. Returns the devicename, connector_type, and connector_number. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT flag must be specified to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


DEFAULTCONNECTION (System Command) - Syntax 
Diagram 


DEFAULTCONNECTION object 

MAKE TO devicename TYPE connector_type TOTYPE connector_type 

NUMBER connector_number TONUMBER connector_number 

BREAK TYPE connector_type 

QUERY 


WAIT 

NOTIFY 


Examples 


DEFAULTCONNECTION (System Command) - Topics 
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GROUP 


GROUP (System Command) - Example 

group mygroup make (cd wavel) wait 


GROUP (System Command) - Purpose 


The GROUP command allows an application to control multiple devices as a unit, or group. Once the group is established, the application 
can control all the devices in the group with a single command. If CLOSE is issued directly to an instance in the group, the instance is 
deleted from the group. 

All other commands addressed to the group must include the NOTIFY flag. 


GROUP (System Command) Keyword - groupname 


groupname 

Refers to a group using a name instead of a group ID. A value for this variable must be specified with the MAKE keyword. 

Note: In use, the variable groupname is the same as an alias. Although the ALIAS keyword is not used, all rules related to ALIAS 
apply to the group name. 


GROUP (System Command) Keyword - MAKE 



MAKE 


Specifies creation of a group by tying several instances together. Once "grouped", the instances can be controlled by the application 
with one command. 

The MAKE keyword requires values for the variables groupname and (il i2 i3). 


GROUP (System Command) Keyword - (il i2 i3) 


(il i2 i3) 

Refers to the device instances that make up the group. Device instances can be identified using aliases, device types, or 
filenames-the same identifiers used when the devices were opened. A value for this variable must be specified with the MAKE 
keyword. 


GROUP (System Command) Keyword - NOPIECEMEAL 


NOPIECEMEAL 

Specifies that the group is to be processed as a whole rather than as separate parts. If one instance becomes inactive, all instances 
become inactive. This keyword is used only with MAKE. 


GROUP (System Command) Keyword - DELETE 


DELETE 

Terminates an existing group by disassociating instances that formed the group. No other keywords, except WAIT or NOTIFY, can be 
used with DELETE. 


GROUP (System Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


GROUP (System Command) Keyword - NOTIFY 



NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


GROUP (System Command) - Keywords 


groupname 

Refers to a group using a name instead of a group ID. A value for this variable must be specified with the MAKE keyword. 

Note: In use, the variable groupname is the same as an alias. Although the ALIAS keyword is not used, all rules related to ALIAS 
apply to the group name. 


MAKE 

Specifies creation of a group by tying several instances together. Once "grouped”, the instances can be controlled by the application 
with one command. 

The MAKE keyword requires values for the variables groupname and (il i2 i3). 

(il i2 13) 

Refers to the device instances that make up the group. Device instances can be identified using aliases, device 
types, or filenames-the same identifiers used when the devices were opened. A value for this variable must be 
specified with the MAKE keyword. 

NOPIECEMEAL 

Specifies that the group is to be processed as a whole rather than as separate parts. If one instance becomes 
inactive, all instances become inactive. This keyword is used only with MAKE. 


DELETE 

Terminates an existing group by disassociating instances that formed the group. No other keywords, except WAIT or NOTIFY, can be 
used with DELETE. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


GROUP (System Command) - Syntax Diagram 


GROUP groupname MAKE (il i2 i3) 

DELETE 


NOPIECEMEAL 


Examples 


WAIT 

NOTIFY 
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MASTERAUDIO 


MASTERAUDIO (System Command) - Example 


masteraudio query volume wait 


MASTERAUDIO (System Command) - Purpose 


The MASTERAUDIO command sets the system master audio setting for all audio devices in the system. The WAIT flag must be specified to 
get string return information for queries. 

This command is used by the OS/2 multimedia Volume Control application to control system-wide audio parameters based on user 
preference. Applications should take special care when using MASTERAUDIO, as it results in a system-wide change. Typically, applications 
control the volume only within an application. 


MASTERAUDIO (System Command) Keyword - VOLUME 
level 


VOLUME level 

Sets the system-wide master volume to the level specified as a percentage. 


MASTERAUDIO (System Command) Keyword - QUERY 
VOLUME 


QUERY VOLUME 

Returns the current application controlled master volume level. 0-100 is returned. 


MASTERAUDIO (System Command) Keyword - QUERY 
HEADPHONES 


QUERY HEADPHONES 

Queries the system-wide headphone setting. ON or OFF is returned. 


MASTERAUDIO (System Command) Keyword - QUERY 
SPEAKERS 


QUERY SPEAKERS 

Queries the system-wide speaker setting. ON or OFF is returned. 


MASTERAUDIO (System Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified to receive return string information. 


MASTERAUDIO (System Command) - Keywords 


VOLUME level 

Sets the system-wide master volume to the level specified as a percentage. 

QUERY VOLUME 

Returns the current application controlled master volume level. 0-100 is returned. 

QUERY HEADPHONES 

Queries the system-wide headphone setting. ON or OFF is returned. 

QUERY SPEAKERS 

Queries the system-wide speaker setting. ON or OFF is returned. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified to receive return string information. 



MASTERAUDIO (System Command) - Syntax Diagram 


MASTERAUDIO VOLUME level 

QUERY VOLUME WAIT 

QUERY HEADPHONES 
QUERY SPEAKERS 


Examples 


MASTERAUDIO (System Command) - Topics 
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RELEASE 


RELEASE (System Command) - Example 


release digitalvideo return resource wait 


RELEASE (System Command) - Purpose 


The RELEASE command releases exclusive use of the physical resources by the device context. 


RELEASE (System Command) Keyword - object 



object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


RELEASE (System Command) Keyword - RETURN 
RESOURCE 


RETURN RESOURCE 

Returns resource for any instance that has requested and is waiting for the resource. If the resource is not requested by another 
instance, it is left active. If resource used is not required by any other instance, it is left active. 


RELEASE (System Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


RELEASE (System Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


RELEASE (System Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

RETURN RESOURCE 

Returns resource for any instance that has requested and is waiting for the resource. If the resource is not requested by another 
instance, it is left active. If resource used is not required by any other instance, it is left active. 


WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


RELEASE (System Command) - Syntax Diagram 


RELEASE object 


RETURN RESOURCE 


WAIT 

NOTIFY 


Examples 
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SYS INFO 


SYSINFO (System Command) - Example 


This command returns all logical device names, separated by a blank. 

sysinfo all name 1 


SYSINFO (System Command) - Purpose 



The SYSINFO command obtains information about the devices installed in the system. This command also accepts ALL as the device 
name, if ALL is used, system information is returned for all devices in the system. 


SYSINFO (System Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


SYSINFO (System Command) Keyword - INSTALLNAME 

INSTALLNAME 

Returns the name that was used to install the device. 


SYSINFO (System Command) Keyword - QUANTITY 


QUANTITY 

Returns the number of media control interface devices of the type specified by the device name. The device name must be a 
standard media control interface device type. Any digits after the name are ignored. The special device name all returns the total 
number of media control interface devices in the system. 


SYSINFO (System Command) Keyword - QUANTITY OPEN 


QUANTITY OPEN 

Returns the number of open media control interface devices of the type specified by the device name. The device name must be a 
standard media control interface device type. Any digits after the name are ignored. The special device name all returns the total 
number of media control interface devices in the system. 


SYSINFO (System Command) Keyword - NAME number 


NAME number 



Returns the name of a media control interface device. The number (ordinal) ranges from 1 to the number of devices of that type. If all 
is specified for the device name, then the number must still be provided, but it is ignored. 


SYSINFO (System Command) Keyword - NAME number 
OPEN 


NAME number OPEN 

Returns the name of an open media control interface device. The number (ordinal) ranges from 1 to the number of devices of that 
type. If all is specified for the device name, then the number must still be provided, but it is ignored and all open device names are 
returned. 


SYSINFO (System Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SYSINFO (System Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

INSTALLNAME 

Returns the name that was used to install the device. 

QUANTITY 

Returns the number of media control interface devices of the type specified by the device name. The device name must be a 
standard media control interface device type. Any digits after the name are ignored. The special device name all returns the total 
number of media control interface devices in the system. 

QUANTITY OPEN 

Returns the number of open media control interface devices of the type specified by the device name. The device name must be a 
standard media control interface device type. Any digits after the name are ignored. The special device name all returns the total 
number of media control interface devices in the system. 

NAME number 

Returns the name of a media control interface device. The number (ordinal) ranges from 1 to the number of devices of that type. If all 
is specified for the device name, then the number must still be provided, but it is ignored. 

NAME number OPEN 

Returns the name of an open media control interface device. The number (ordinal) ranges from 1 to the number of devices of that 
type. If all is specified for the device name, then the number must still be provided, but it is ignored and all open device names are 
returned. 


WAIT 



The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SYSINFO (System Command) - Syntax Diagram 


SYSINFO object INSTALLNAME 

QUANTITY WAIT 

QUANTITY OPEN 
NAME number 
NAME number OPEN 


Examples 
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Required Commands 


Required commands are standard commands that are recognized by a// MCI devices. Additional options can be added to extend these 
commands, however an MCI device must still support the required options. The following commands are required commands: 

CAPABILITY 

• CLOSE 
INFO 

• OPEN 

• STATUS 


CAPABILITY 


CAPABILITY (Required Command) - Example 



capability waveaudioOl can record wait 


CAPABILITY (Required Command) - Purpose 


The CAPABILITY command requests the information about a particular capability of a device. 


CAPABILITY (Required Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CAPABILITY (Required Command) Keyword - CAN EJECT 


CAN EJECT 

Returns TRUE if the device can eject the media. 


CAPABILITY (Required Command) Keyword - CAN PLAY 


CAN PLAY 

Returns TRUE if the device can play. 


CAPABILITY (Required Command) Keyword - CAN RECORD 


CAN RECORD 

Returns TRUE if the device supports recording. 


CAPABILITY (Required Command) Keyword - CAN SAVE 



CAN SAVE 

Returns TRUE if the device can save data. 


CAPABILITY (Required Command) Keyword - CAN 
LOCKEJECT 


CAN LOCKEJECT 

Returns TRUE if the device can disable the manual ejection of the media. 


CAPABILITY (Required Command) Keyword - CAN 
SETVOLUME 


CAN SETVOLUME 

Returns TRUE if the device supports software control of volume level. 


CAPABILITY (Required Command) Keyword - COMPOUND 
DEVICE 


COMPOUND DEVICE 

Returns TRUE if the device requires an element name. 


CAPABILITY (Required Command) Keyword - DEVICE TYPE 


DEVICE TYPE 

Returns one of the following: 

• ampmix 

• cdaudio 

• cdxa 

• digitalvideo 

• overlay 

• sequencer 

• videodisc 

• waveaudio 

• other 



CAPABILITY (Required Command) Keyword - HAS AUDIO 


HAS AUDIO 

Returns TRUE if the device supports audio playback. 


CAPABILITY (Required Command) Keyword - HAS VIDEO 

HAS VIDEO 

Returns TRUE if the device supports video playback. 


CAPABILITY (Required Command) Keyword - MESSAGE 
command 


MESSAGE command 

Returns TRUE if the device supports the command specified by command. Following are the commands you can query: 


ACQUIRE 

CAPABILITY 

CLOSE 

CONNECTION 

CONNECTOR 

CUE 

ESCAPE 

GROUP 

INFO 

LOAD 

MASTERAUDIO 

OPEN 

PAUSE 

PLAY 


RECORD 

RELEASE 

RESUME 

SAVE 

SEEK 

SET 

SETCUEPOINT 

SETPOSITIONADVISE 

SPIN 

STATUS 

STEP 

STOP 

SYS INFO 


CAPABILITY (Required Command) Keyword - PREROLL 
TIME 


PREROLL TIME 

Returns the deterministic or maximum notified preroll time in MMTIME units. A value of 0 for a notified preroll device indicates the 
preroll time is not bounded. 


CAPABILITY (Required Command) Keyword - PREROLL 



TYPE 


PREROLL TYPE 

Returns the preroll characteristics of the device. Returns notified if the preroll time for the device is variable. Returns deterministic if 
the prerolled time for the device is fixed. Returns none if the device does not support preroll. 


CAPABILITY (Required Command) Keyword - USES FILES 

USES FILES 

Returns TRUE if the device requires a file path name. 


CAPABILITY (Required Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


CAPABILITY (Required Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPABILITY (Required Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

While other capabilities are defined for specific devices and device types, the following keywords can always be specified: 


CAN EJECT 

Returns TRUE if the device can eject the media. 


CAN PLAY 


Returns TRUE if the device can play. 

CAN RECORD 

Returns TRUE if the device supports recording. 

CAN SAVE 

Returns TRUE if the device can save data. 

CAN LOCKEJECT 

Returns TRUE if the device can disable the manual ejection of the media. 

CAN SETVOLUME 

Returns TRUE if the device supports software control of volume level. 

COMPOUND DEVICE 

Returns TRUE if the device requires an element name. 

DEVICE TYPE 

Returns one of the following: 

• ampmix 

• cdaudio 

• cdxa 

• digitalvideo 

• overlay 

• sequencer 

• videodisc 

• waveaudio 

• other 


HAS AUDIO 

Returns TRUE if the device supports audio playback. 

HAS VIDEO 

Returns TRUE if the device supports video playback. 


MESSAGE command 

Returns TRUE if the device supports the command specified by command. Following are the commands you can query: 


ACQUIRE 

CAPABILITY 

CLOSE 

CONNECTION 

CONNECTOR 

CUE 

ESCAPE 

GROUP 

INFO 

LOAD 

MASTERAUDIO 

OPEN 

PAUSE 

PLAY 


RECORD 

RELEASE 

RESUME 

SAVE 

SEEK 

SET 

SETCUEPOINT 

SETPOSITIONADVISE 

SPIN 

STATUS 

STEP 

STOP 

SYS INFO 


PREROLL TIME 

Returns the deterministic or maximum notified preroll time in MMTIME units. A value of 0 for a notified preroll device indicates the 
preroll time is not bounded. 


PREROLL TYPE 

Returns the preroll characteristics of the device. Returns notified if the preroll time for the device is variable. Returns deterministic if 
the prerolled time for the device is fixed. Returns none if the device does not support preroll. 


USES FILES 

Returns TRUE if the device requires a file path name. 

WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 


The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


CAPABILITY (Required Command) - Syntax Diagram 


CAPABILITY object CAN EJECT 

CAN PLAY 
CAN RECORD 
CAN SAVE 
CAN LOCKE JECT 
CAN SETVOLUME 
COMPOUND DEVICE 
DEVICE TYPE 
HAS AUDIO 
HAS VIDEO 
MESSAGE command 
PREROLL TIME 
PREROLL TYPE 
USES FILES 


WAIT 

NOTIFY 


Examples 
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CLOSE 


CLOSE (Required Command) - Example 


close digitalvideo wait 


CLOSE (Required Command) - Purpose 



The CLOSE command closes the device context and frees resources. 


CLOSE (Required Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


CLOSE (Required Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CLOSE (Required Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CLOSE (Required Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CLOSE (Required Command) - Syntax Diagram 


CLOSE object 


WAIT 

NOTIFY 


Examples 


CLOSE (Required Command) - Topics 
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INFO 


INFO (Required Command) - Example 


info digitalvideo product 


INFO (Required Command) - Purpose 


The INFO command fills a user-supplied buffer with information. 


INFO (Required Command) Keyword - object 



object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


INFO (Required Command) Keyword - PRODUCT 


PRODUCT 

Returns a description of the hardware associated with a device. This usually includes the manufacturer and model information. 


INFO (Required Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


INFO (Required Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


INFO (Required Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

PRODUCT 

Returns a description of the hardware associated with a device. This usually includes the manufacturer and model information. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


INFO (Required Command) - Syntax Diagram 


INFO object PRODUCT 

WAIT 

NOTIFY 


Examples 
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OPEN 


OPEN (Required Command) - Example 


open applause.wav shareable alias wfile wait 
play wfile notify 


OPEN (Required Command) - Purpose 


The OPEN command is used to open or create a new device instance. 



OPEN returns a device ID that is used for subsequent calls for procedure interface, if desired. 


OPEN (Required Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


OPEN (Required Command) Keyword - ALIAS devicealias 


ALIAS devicealias 

Specifies an alternate name for the given device. If an alias is specified, it must be used in subsequent references to avoid automatic 
open. Following are descriptions of what an alias can be: 

• Any word that is not a keyword 

• Any valid filename 

• Any string of words enclosed in double quotes, for example: 

"CD Player" 


If a string is used, any leading and trailing blanks are ignored and internal blanks are preserved. Uppercase and lowercase can be 
used, but an alias is case insensitive. 


OPEN (Required Command) Keyword - DOSQUEUE 


DOSQUEUE 

If a device instance is opened with the DOSQUEUE keyword specified, window handles that are passed in for the instance will be 
treated as OS/2 Control Program queue handles. 


OPEN (Required Command) Keyword - READONLY 


READONLY 

Specifies that the file is to be opened in read-only mode. 


OPEN (Required Command) Keyword - SHAREABLE 



SHAREABLE 

Initializes the device as shareable. Specifying shareable makes the resources of the device available to other device contexts. If 
SHAREABLE is not specified with OPEN, the resource will be exclusively acquired when the device is opened. 


OPEN (Required Command) Keyword - TYPE devicetype 


TYPE devicetype 

Specifies the compound device used to control a device element. As an alternative to TYPE, an application can specify the name of a 
file to be opened. The media control interface uses the file EA or extension associated with the file to select the controlling device. 


OPEN (Required Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


OPEN (Required Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


OPEN (Required Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

ALIAS devlcealias 

Specifies an alternate name for the given device. If an alias is specified, it must be used in subsequent references to avoid automatic 
open. Following are descriptions of what an alias can be: 

■ Any word that is not a keyword 

• Any valid filename 

• Any string of words enclosed in double quotes, for example: 


CD Player 


If a string is used, any leading and trailing blanks are ignored and internal blanks are preserved. Uppercase and lowercase can be 
used, but an alias is case insensitive. 

DOSQUEUE 

If a device instance is opened with the DOSQUEUE keyword specified, window handles that are passed in for the instance will be 
treated as OS/2 Control Program queue handles. 

READONLY 

Specifies that the file is to be opened in read-only mode. 

SHAREABLE 

Initializes the device as shareable. Specifying shareable makes the resources of the device available to other device contexts. If 
SHAREABLE is not specified with OPEN, the resource will be exclusively acquired when the device is opened. 

TYPE devicetype 

Specifies the compound device used to control a device element. As an alternative to TYPE, an application can specify the name of a 
file to be opened. The media control interface uses the file EA or extension associated with the file to select the controlling device. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


OPEN (Required Command) - Syntax Diagram 


OPEN object 

ALIAS devicealias WAIT 

DOSQUEUE NOTIFY 

READONLY 

SHAREABLE 

TYPE devicetype 


Examples 
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STATUS 



STATUS (Required Command) - Example 


status waveaudioOl mode wait 


STATUS (Required Command) - Purpose 


The STATUS command obtains status information for the device. 


STATUS (Required Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


STATUS (Required Command) Keyword - MODE 


MODE 

Returns the current mode of the device: not ready, stopped, playing, seeking, recording, paused, or other. 


STATUS (Required Command) Keyword - READY 


READY 

Returns TRUE if the device is ready. 


STATUS (Required Command) Keyword - WAIT 



WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


STATUS (Required Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (Required Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


MODE 

Returns the current mode of the device: not ready, stopped, playing, seeking, recording, paused, or other. 

READY 

Returns TRUE if the device is ready. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (Required Command) - Syntax Diagram 


STATUS object MODE 

READY WAIT 

NOTIFY 


Examples 
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Basic Commands 


In addition to the system and required commands, each device supports a set of device-type specific commands. Where possible, these 
type-specific commands are identical between device types. When type-specific commands are common to multiple devices, they are 
considered basic commands. For example, the basic PLAY command is identical for videodisc, wave audio, and CD audio players. 

Although these commands are optional for a device, if a command is used it must recognize the options listed here and return 
MCIERR_UNSUPPORTED_FLAG for options that are not applicable. 

For those devices that do not support a basic command, such as a RECORD command sent to a CD audio player, an 
MCIERR_UNSUPPORTED_FUNCTION is returned by that MCD. If a message is sent to a device that is not recognized, then 
MCIERR_UNRECOGNIZED_COMMAND is returned. Before using a basic command, an application can issue a CAPABILITY query to see 
if the device supports the command. 

The following commands are basic commands: 

• CONNECTION 
CONNECTOR 

• LOAD 
PAUSE 

• PLAY 
RECORD 

• RESUME 
SAVE 

• SEEK 
SET 

• SETCUEPOINT 
SETPOSITIONADVISE 

• STATUS 

• STOP 


CONNECTOR 


CONNECTOR (Basic Command) - Example 


connector waveaudioOl enable type microphone 


CONNECTOR (Basic Command) - Purpose 

The CONNECTOR command enables, disables, or queries the status of connectors on a device. 


CONNECTOR (Basic Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CONNECTOR (Basic Command) Keyword - ENABLE 


ENABLE 

Enables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
must also be specified. 


CONNECTOR (Basic Command) Keyword - DISABLE 


DISABLE 

Disables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
must also be specified. 


CONNECTOR (Basic Command) Keyword - QUERY 


QUERY 

Queries the status of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled 
respectively. Use of this option requires that the NUMBER or TYPE keywords, or both must also be specified. 


CONNECTOR (Basic Command) Keyword - NUMBER 



connector number 


NUMBER connectornumber 

The connector number on which to perform the requested action. If this item is omitted, the first connector is assumed. If the TYPE 
keyword is included, then the connector number is interpreted as a relative offset within the specified connector type. 


CONNECTOR (Basic Command) Keyword - TYPE 
connector_type 


TYPE connector type 

The type of connector to which the requested action applies. See the TYPE keyword for CONNECTION for a list of connector types. 


CONNECTOR (Basic Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CONNECTOR (Basic Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTOR (Basic Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

ENABLE 

Enables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
must also be specified. 


DISABLE 


Disables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
must also be specified. 

QUERY 

Queries the status of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled 
respectively. Use of this option requires that the NUMBER or TYPE keywords, or both must also be specified. 

NUMBER connector number 

The connector number on which to perform the requested action. If this item is omitted, the first connector is assumed. If the TYPE 
keyword is included, then the connector number is interpreted as a relative offset within the specified connector type. 

TYPE connector type 

The type of connector to which the requested action applies. See the TYPE keyword for CONNECTION for a list of connector types. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


CONNECTOR (Basic Command) - Syntax Diagram 


CONNECTOR object 


ENABLE 

DISABLE 

QUERY 


NUMBER connector_number 

TYPE connector_type WAIT 

NOTIFY 


Examples 


CONNECTOR (Basic Command) - Topics 


Select an item: 

Purpose 

Syntax Diagram 

Keywords 

Example 

Glossary 


LOAD 



LOAD (Basic Command) - Example 


open digitalvideoOl alias videol wait 
load videol movie.avi wait 


LOAD (Basic Command) - Purpose 


The LOAD command loads a new device element (file) into an already open device context. 


LOAD (Basic Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


LOAD (Basic Command) Keyword - filename 


filename 

Name of the file to be loaded. 


LOAD (Basic Command) Keyword - NEW 


NEW 

Creates a temporary element for subsequent use. The temporary file can be made permanent by providing a name using the SAVE 
command. 


LOAD (Basic Command) Keyword - WAIT 


WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


LOAD (Basic Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


LOAD (Basic Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

filename 

Name of the file to be loaded. 


NEW 

Creates a temporary element for subsequent use. The temporary file can be made permanent by providing a name using the SAVE 
command. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


LOAD (Basic Command) - Syntax Diagram 


LOAD object 


filename 

NEW 


WAIT 

NOTIFY 


Examples 
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PAUSE 


PAUSE (Basic Command) - Example 

pause videol wait 


PAUSE (Basic Command) - Purpose 


The PAUSE command stops playing or recording. The difference between PAUSE and STOP is device dependent. On video devices, 
PAUSE generally continues to display the last frame, whereas STOP causes the display to blank. A device that is paused can frequently 
begin playing again with less latency than if it were stopped. 


PAUSE (Basic Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


PAUSE (Basic Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


PAUSE (Basic Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


PAUSE (Basic Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


PAUSE (Basic Command) - Syntax Diagram 


PAUSE object 


WAIT 

NOTIFY 


Examples 


PAUSE (Basic Command) - Topics 
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PLAY 


PLAY (Basic Command) - Example 


play digitalvideo wait 


PLAY (Basic Command) - Purpose 


The PLAY command starts playing the device. 

Note: PLAY can be used on a file without a preceding OPEN. 


PLAY (Basic Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


PLAY (Basic Command) Keyword - FROM pos 


FROM pos 

Specifies the position at which to start playing. If FROM is omitted, the device starts playing at the current position: if TO is omitted, 
the device plays to the end position. 


PLAY (Basic Command) Keyword - TO pos 



TO pos 

Specifies the position at which to stop playing. If FROM is omitted, the device starts playing at the current position; if TO is omitted, 
the device plays to the end position. 


PLAY (Basic Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


PLAY (Basic Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


PLAY (Basic Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

FROM pos 

Specifies the position at which to start playing. If FROM is omitted, the device starts playing at the current position: if TO is omitted, 
the device plays to the end position. 

TO pos 

Specifies the position at which to stop playing. If FROM is omitted, the device starts playing at the current position; if TO is omitted, 
the device plays to the end position. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


PLAY (Basic Command) - Syntax Diagram 


PLAY 


object 


FROM pos 
TO pos 


WAIT 

NOTIFY 


Examples 


PLAY (Basic Command) - Topics 


Select an item: 

Purpose 

Syntax Diagram 

Keywords 

Example 

Glossary 


RECORD 


RECORD (Basic Command) - Example 

record digitalvideo notify 


RECORD (Basic Command) - Purpose 


The RECORD command starts recording data. By default, recording does not overwrite existing data but rather inserts data at the current 
position. On devices that cannot support inserting data (such as audio or video tape), recording overwrites existing data by default. 


RECORD (Basic Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 



Filename 

Alias 


RECORD (Basic Command) Keyword - FROM pos 


FROM pos 

Specifies the position at which to start recording. If FROM is omitted, the device starts recording at the current position; if TO is 
omitted, the device records to the end position. 


RECORD (Basic Command) Keyword - TO pos 


TO pos 

Specifies the position at which to stop recording. If FROM is omitted, the device starts recording at the current position; if TO is 
omitted, the device records to the end position. 


RECORD (Basic Command) Keyword - INSERT 


INSERT 

Data is to be added to the device element. This is the default on devices that support insertion of data (file-oriented devices). Returns 
MCI_UNSUPPORTED_FLAG on devices that do not support INSERT. 


RECORD (Basic Command) Keyword - OVERWRITE 


OVERWRITE 

Recorded data replaces existing data in the device element. This is the default on devices that do not support insertion of data (for 
example, videotape). 


RECORD (Basic Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 



RECORD (Basic Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


RECORD (Basic Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

FROM pos 

Specifies the position at which to start recording. If FROM is omitted, the device starts recording at the current position; if TO is 
omitted, the device records to the end position. 

TO pos 

Specifies the position at which to stop recording. If FROM is omitted, the device starts recording at the current position; if TO is 
omitted, the device records to the end position. 

INSERT 

Data is to be added to the device element. This is the default on devices that support insertion of data (file-oriented devices). Returns 
MCI_UNSUPPORTED_FLAG on devices that do not support INSERT. 

OVERWRITE 

Recorded data replaces existing data in the device element. This is the default on devices that do not support insertion of data (for 
example, videotape). 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


RECORD (Basic Command) - Syntax Diagram 


RECORD object 


FROM pos 
TO pos 


INSERT 

OVERWRITE 


WAIT 

NOTIFY 


Examples 
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RESUME 


RESUME (Basic Command) - Example 


resume waveaudioOl wait 


RESUME (Basic Command) - Purpose 


The RESUME command resumes playing or recording from a paused state, keeping previously specified parameters in effect. 


RESUME (Basic Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


RESUME (Basic Command) Keyword - WAIT 



WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


RESUME (Basic Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


RESUME (Basic Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


RESUME (Basic Command) - Syntax Diagram 


RESUME object 


WAIT 

NOTIFY 


Examples 


RESUME (Basic Command) - Topics 
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SAVE 


SAVE (Basic Command) - Example 


open macaw.avi alias videol wait 
save videol movie.avi wait 


SAVE (Basic Command) - Purpose 


The SAVE command saves data for the device. 


SAVE (Basic Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following 

• Device type 

• Device name 

• Filename 

• Alias 


SAVE (Basic Command) Keyword - filename 


filename 

The destination path and filename. 


SAVE (Basic Command) Keyword - WAIT 


WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SAVE (Basic Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SAVE (Basic Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

filename 

The destination path and filename. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SAVE (Basic Command) - Syntax Diagram 


SAVE object filename 


WAIT 

NOTIFY 


Examples 


SAVE (Basic Command) - Topics 
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SEEK 


SEEK (Basic Command) - Example 


seek digitalvideo to start wait 


SEEK (Basic Command) - Purpose 


The SEEK command finds the specified position and stops. 


SEEK (Basic Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


SEEK (Basic Command) Keyword - TO pos 


TO pos 

The position at which to stop the seek. If it is greater than the length of the media, an OUT OF RANGE error is returned. 


SEEK (Basic Command) Keyword - TO START 


TO START 

Seek to the beginning of the media. 


SEEK (Basic Command) Keyword - TO END 


TO END 

Seek to the end of the media. 


SEEK (Basic Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SEEK (Basic Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SEEK (Basic Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


TO pos 

The position at which to stop the seek. If it is greater than the length of the media, an OUT OF RANGE error is returned. 

TO START 

Seek to the beginning of the media. 


TO END 


Seek to the end of the media. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SEEK (Basic Command) - Syntax Diagram 


SEEK 

object 

TO 

pos 



TO 

START 



TO 

END 


WAIT 

NOTIFY 


Examples 


SEEK (Basic Command) - Topics 


Select an item: 

Purpose 

Syntax Diagram 

Keywords 

Example 

Glossary 


SET 


SET (Basic Command) - Example 

set waveaudioOl time format milliseconds wait 


SET (Basic Command) - Purpose 



The SET command sets the various control items. 


SET (Basic Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


SET (Basic Command) Keyword - AUDIO 


AUDIO 

Sets the audio attributes of the device context specified by the ALL, LEFT, RIGFIT, OVER, and VOLUME keywords. 


SET (Basic Command) Keyword - ALL 


ALL 

Apply to both or all of the channels (default). 
Specify ON or OFF with the ALL keyword. 


SET (Basic Command) Keyword - ON 


ON 

Enable audio output. 


SET (Basic Command) Keyword - OFF 


OFF 


Disable audio output. 



SET (Basic Command) Keyword - LEFT 


LEFT 

Apply to the left channel. 

Specify ON or OFF with the LEFT keyword. 


SET (Basic Command) Keyword - ON 


ON 

Enable audio output to the left channel. 


SET (Basic Command) Keyword - OFF 


OFF 

Disable audio output to the left channel. 


SET (Basic Command) Keyword - RIGFIT 


RIGHT 

Apply to the right channel. 

Specify ON or OFF with the RIGFIT keyword. 


SET (Basic Command) Keyword - ON 


ON 

Enable audio output to the right channel. 


SET (Basic Command) Keyword - OFF 



OFF 


Disable audio output to the right channel. 


SET (Basic Command) Keyword - OVER milliseconds 


OVER milliseconds 

Apply the change over the specified time period (fade). 


SET (Basic Command) Keyword - VOLUME percentage 


VOLUME percentage 

Set the device/mixer channel volume level. 


SET (Basic Command) Keyword - DOOR CLOSED 


DOOR CLOSED 

Retracts the tray and closes the door, if possible. 


SET (Basic Command) Keyword - DOOR OPEN 


DOOR OPEN 

Opens the door and ejects the tray, if possible. 


SET (Basic Command) Keyword - DOOR LOCKED 


DOOR LOCKED 

Locks the media cover on the device (if any). This disables manual ejection of the media from the device. 


SET (Basic Command) Keyword - DOOR UNLOCKED 



DOOR UNLOCKED 

Unlocks the media cover on the device (if any). This enables manual ejection of the media from the device. 


SET (Basic Command) Keyword - SPEED FORMAT 
PERCENTAGE 


SPEED FORMAT PERCENTAGE 

Sets the speed format to percentage. 


SET (Basic Command) Keyword - SPEED FORMAT FPS 


SPEED FORMAT FPS 

Sets the speed format to frames per second. 


SET (Basic Command) Keyword - TIME FORMAT 
MILLISECONDS 


TIME FORMAT MILLISECONDS 

Sets the time format, to milliseconds. You can abbreviate milliseconds as ms. 


SET (Basic Command) Keyword - TIME FORMAT MMTIME 


TIME FORMAT MMTIME 

Sets the time format to MMTIME. 


SET (Basic Command) Keyword - VIDEO OFF 


VIDEO OFF 

Disables video output. 


SET (Basic Command) Keyword - VIDEO ON 



VIDEO ON 

Enables video output. 


SET (Basic Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SET (Basic Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SET (Basic Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 

AUDIO 

Sets the audio attributes of the device context specified by the ALL, LEFT, RIGHT, OVER, and VOLUME keywords. 

ALL 

Apply to both or all of the channels (default). 

Specify ON or OFF with the ALL keyword. 

ON 

Enable audio output. 

OFF 

Disable audio output. 

LEFT 

Apply to the left channel. 

Specify ON or OFF with the LEFT keyword. 

ON 

Enable audio output to the left channel. 


OFF 


Disable audio output to the left channel. 


RIGHT 


Apply to the right channel. 

Specify ON or OFF with the FtIGFIT keyword. 

ON 

Enable audio output to the right channel. 


OFF 


Disable audio output to the right channel. 


OVER milliseconds 

Apply the change over the specified time period (fade). 

VOLUME percentage 

Set the device/mixer channel volume level. 


DOOR CLOSED 

Retracts the tray and closes the door, if possible. 

DOOR OPEN 

Opens the door and ejects the tray, if possible. 

DOOR LOCKED 

Locks the media cover on the device (if any). This disables manual ejection of the media from the device. 

DOOR UNLOCKED 

Unlocks the media cover on the device (if any). This enables manual ejection of the media from the device. 

SPEED FORMAT PERCENTAGE 

Sets the speed format to percentage. 

SPEED FORMAT FPS 

Sets the speed format to frames per second. 

TIME FORMAT MILLISECONDS 

Sets the time format, to milliseconds. You can abbreviate milliseconds as ms. 

TIME FORMAT MMTIME 

Sets the time format to MMTIME. 

VIDEO OFF 

Disables video output. 

VIDEO ON 

Enables video output. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


SET (Basic Command) - Syntax Diagram 


SET object AUDIO 

ALL ON 

OFF 

LEFT ON 

OFF 
ON 


RIGHT 


OFF 

OVER milliseconds 
VOLUME percentage 

DOOR CLOSED 

DOOR OPEN 

DOOR LOCKED 

DOOR UNLOCKED 

SPEED FORMAT PERCENTAGE 

SPEED FORMAT FPS 

TIME FORMAT MILLISECONDS 

TIME FORMAT MMTIME 

VIDEO OFF 

VIDEO ON 


WAIT 

NOTIFY 


Examples 
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SETCUEPOINT 


SETCUEPOINT (Basic Command) - Example 


setcuepoint waveaudioOl on at 5000 wait 


SETCUEPOINT (Basic Command) - Purpose 


The SETCUEPOINT command sets a cue point. The window handle specified in the hi vndCa//Back parameter of mciSendString receives 
the cue point notification (MM_MCICUEPOINT) messages. 


This command is not related to the CUE command. 



SETCUEPOINT (Basic Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


SETCUEPOINT (Basic Command) Keyword - ON AT position 


ON AT position 

Specifies the location of the cuepoint to enable in the currently set time format. 


SETCUEPOINT (Basic Command) Keyword - OFF AT 
position 


OFF AT position 

Specifies the location of the cuepoint to disable in the currently set time format. 


SETCUEPOINT (Basic Command) Keyword - RETURN value 


RETURN value 

A value to be returned in the user parameter field of the cue point notification message (MM_MCICUEPOINT). 


SETCUEPOINT (Basic Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SETCUEPOINT (Basic Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


ON AT position 

Specifies the location of the cuepoint to enable in the currently set time format. 

OFF AT position 

Specifies the location of the cuepoint to disable in the currently set time format. 

RETURN value 

A value to be returned in the user parameter field of the cue point notification message (MM_MCICUEPOINT). 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 



object 


Object associated with this media control interface command. The object can be one of the following: 


Device type 
Device name 
Filename 
Alias 


SETCUEPOINT (Basic Command) - Syntax Diagram 


SETCUEPOINT 


object 


ON AT position 
OFF AT position 


RETURN value 


WAIT 

NOTIFY 


Examples 



Devices that do not perform their own event detection might have less accurate cue points. 
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SETPOSITION ADVISE 


SETPOSITIONADVISE (Basic Command) - Example 


setpositionadvise waveaudioOl off wait 


SETPOSITIONADVISE (Basic Command) - Purpose 


The SETPOSITIONADVISE command sets a position change notification for the device. The window handle specified in the /mr)dCa//Back 
parameter of mciSendString receives the position change notification (MM_MCIPOSITIONCHANGE) messages. 


SETPOSITIONADVISE (Basic Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


SETPOSITIONADVISE (Basic Command) Keyword - ON 


ON 


Enables the given position advise. 


SETPOSITION ADVISE (Basic Command) Keyword - EVERY 
units 


EVERY units 

The position change notification granularity in the currently set time format. 


SETPOSITION ADVISE (Basic Command) Keyword - OFF 


OFF 

Disables the given position advise. 


SETPOSITIONADVISE (Basic Command) Keyword - 
RETURN value 


RETURN value 

A value to be returned in the user parameter field of the position change notification message (MM_MCIPOSITIONCHANGE). 


SETPOSITIONADVISE (Basic Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SETPOSITIONADVISE (Basic Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SETPOSITIONADVISE (Basic Command) - Keywords 


object 


Object associated with this media control interface command. The object can be one of the following: 


Device type 
Device name 
Filename 
Alias 


You must specify either the ON or OFF keyword. 


ON 


Enables the given position advise. 


EVERY units 


The position change notification granularity in the currently set time format. 


OFF 

Disables the given position advise. 

RETURN value 

A value to be returned in the user parameter field of the position change notification message (MM_MCIPOSITIONCFIANGE). 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SETPOSITIONADVISE (Basic Command) - Syntax Diagram 


SETPOSITIONADVISE 


object 


ON 


EVERY units 


OFF 


RETURN value 


WAIT 

NOTIFY 


Examples 



Devices that do not perform their own event detection might have less accurate position-advise events. 
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STATUS 


STATUS (Basic Command) - Example 


status waveaudioOl volume wait 


STATUS (Basic Command) - Purpose 


The STATUS command obtains status information for the device. 


STATUS (Basic Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


STATUS (Basic Command) Keyword - CURRENT TRACK 


CURRENT TRACK 

Returns the current track. 


STATUS (Basic Command) Keyword - LENGTH 


LENGTH 

Returns the total length of the segment. For compound devices, such as waveaudio, a device element must be opened or loaded to 
obtain the length. 


STATUS (Basic Command) Keyword - LENGTH TRACK 
number 


LENGTH TRACK number 

Returns the length of the track specified by number. Returned value is in MMTIME units unless the object has been opened and its 
time format has been changed. 


STATUS (Basic Command) Keyword - NUMBER OF 
TRACKS 


NUMBER OF TRACKS 

Returns the number of tracks on the media. 


STATUS (Basic Command) Keyword - POSITION 


POSITION 

Returns the current position. 


STATUS (Basic Command) Keyword - POSITION IN TRACK 


POSITION IN TRACK 

Returns the current position relative to the beginning of the track. 



STATUS (Basic Command) Keyword - POSITION TRACK 
number 


POSITION TRACK number 

Returns the position of the start of the track specified by number. Returned value is in MMTIME units unless the object has been 
opened and its time format has been changed. 


STATUS (Basic Command) Keyword - SPEED FORMAT 


SPEED FORMAT 

Returns the speed format. 


STATUS (Basic Command) Keyword - TIME FORMAT 


TIME FORMAT 

Returns the time format. 


STATUS (Basic Command) Keyword - VOLUME 


VOLUME 

Returns the current volume setting. The volume is returned as a string in the format /eft.right where /eft and right are percentages of 
the maximum achievable effect for the left and right channels respectively. Leading zeros are suppressed for the volume level in each 
channel. 


STATUS (Basic Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


STATUS (Basic Command) Keyword - NOTIFY 



NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (Basic Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 

CURRENT TRACK 

Returns the current track. 

LENGTH 

Returns the total length of the segment. For compound devices, such as waveaudio, a device element must be opened or loaded to 
obtain the length. 

LENGTH TRACK number 

Returns the length of the track specified by number. Returned value is in MMTIME units unless the object has been opened and its 
time format has been changed. 

NUMBER OF TRACKS 

Returns the number of tracks on the media. 

POSITION 

Returns the current position. 

POSITION IN TRACK 

Returns the current position relative to the beginning of the track. 

POSITION TRACK number 

Returns the position of the start of the track specified by number. Returned value is in MMTIME units unless the object has been 
opened and its time format has been changed. 

SPEED FORMAT 

Returns the speed format. 

TIME FORMAT 

Returns the time format. 

VOLUME 

Returns the current volume setting. The volume is returned as a string in the format /eft.right where /eft and right are percentages of 
the maximum achievable effect for the left and right channels respectively. Leading zeros are suppressed for the volume level in each 
channel. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


STATUS (Basic Command) - Syntax Diagram 


STATUS object CURRENT TRACK 

LENGTH 

LENGTH TRACK number 
NUMBER OF TRACKS 
POSITION 

POSITION IN TRACK 
POSITION TRACK number 
SPEED FORMAT 
TIME FORMAT 
VOLUME 


WAIT 

NOTIFY 


Examples 
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STOP 


STOP (Basic Command) - Example 


stop digitalvideoOl wait 


STOP (Basic Command) - Purpose 


The STOP command stops the device. 


STOP (Basic Command) Keyword - object 



object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


STOP (Basic Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


STOP (Basic Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STOP (Basic Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STOP (Basic Command) - Syntax Diagram 


STOP 


object 


WAIT 

NOTIFY 


Examples 


STOP (Basic Command) - Topics 
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Audio Amplifier Mixer Commands 


The audio amplifier mixer device supports extensions to the basic and required command sets. A device context of the audio amplifier mixer 
is a channel, either stereo or monaural, so most commands apply to channel levels. The exception is commands that apply to the final 
(output) mix, such as master volume. 

Note that volume commands can be sent directly to player devices. These devices forward the volume command to the connected audio 
amplifier mixer channel device context when the output of the player is to an amplifier mixer. Other shaping functions, such as bass and 
treble, must be sent to the amplifier mixer. 

The ampmix device is a conduit of information and relies on another device to provide the flow of information. Therefore, commands for the 
transport of information (such as play, seek, or stop), are sent to the attached device. Commands for transforming the information (such as 
treble or bass) are sent directly to the ampmix device. If the application needs to talk directly to the ampmix device, the value of the stream 
connector can be queried using the CONNECTION command, which returns a device context connection. An alias can be established for 
the connected device. Ampmix commands can then be sent directly to the ampmix device. 

The ampmix device supports the device-type specific command, MIXNOTIFY, and extensions to the following basic and required 
commands: 


• CAPABILITY 
CONNECTOR 

• MIXNOTIFY 

• SET 

• STATUS 


CAPABILITY 


CAPABILITY (Mixer Command) - Example 



The following command returns FALSE. 

capability ampmixOl can record wait 


CAPABILITY (Mixer Command) - Purpose 


The CAPABILITY command requests additional information about the capabilities of the audio amplifier mixer device. 


CAPABILITY (Mixer Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CAPABILITY (Mixer Command) Keyword - CAN EJECT 


CAN EJECT 

Returns FALSE. 


CAPABILITY (Mixer Command) Keyword - CAN LOCK 
EJECT 


CAN LOCK EJECT 

Returns FALSE. 


CAPABILITY (Mixer Command) Keyword - CAN PLAY 


CAN PLAY 

Returns FALSE. 



CAPABILITY (Mixer Command) Keyword - CAN PROCESS 
INTERNAL 


CAN PROCESS INTERNAL 

Returns FALSE. 


CAPABILITY (Mixer Command) Keyword - CAN RECORD 


CAN RECORD 

Returns FALSE. 


CAPABILITY (Mixer Command) Keyword - CAN SAVE 


CAN SAVE 

Returns FALSE. 


CAPABILITY (Mixer Command) Keyword - CAN STREAM 


CAN STREAM 

Returns FALSE. 


CAPABILITY (Mixer Command) Keyword - CAN SET 
VOLUME 


CAN SET VOLUME 

Returns TRUE. 


CAPABILITY (Mixer Command) Keyword - COMPOUND 
DEVICE 



COMPOUND DEVICE 

Returns FALSE. 


CAPABILITY (Mixer Command) Keyword - DEVICE TYPE 


DEVICE TYPE 

Returns Ampmix. 


CAPABILITY (Mixer Command) Keyword - HAS AUDIO 


HAS AUDIO 

Returns TRUE. 


CAPABILITY (Mixer Command) Keyword - HAS VIDEO 


HAS VIDEO 

Returns FALSE. 


CAPABILITY (Mixer Command) Keyword - MESSAGE 
command 


MESSAGE command 

Returns TRUE if the device supports the command specified by command The command can be any of the string commands such 
as OPEN, PLAY, and so on. 


CAPABILITY (Mixer Command) Keyword - PREROLL TIME 


PREROLL TIME 

Returns 0, indicating the preroll time is not bounded. 



CAPABILITY (Mixer Command) Keyword - PREROLL TYPE 


PREROLL TYPE 

Returns NONE. 


CAPABILITY (Mixer Command) Keyword - USES FILES 


USES FILES 

Returns FALSE. 


CAPABILITY (Mixer Command) Keyword - EXTENDED 
MIXER CONNECTOR type 


EXTENDED MIXER CONNECTOR type 

Indicates that a mixer format will be queried. The type specified must be a valid connector type. If the EXTENDED MIXER keywords 
are specified, the SUPPORTS keyword must also be specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS 
AUTO LEVEL CONTROL 


SUPPORTS AUTO LEVEL CONTROL 

Indicates whether auto-level control settings are supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS 
BALANCE 


SUPPORTS BALANCE 

Indicates whether balance settings are supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS BASS 



SUPPORTS BASS 

Indicates whether bass settings are supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS 
CHORUS 


SUPPORTS CHORUS 

Indicates whether chorus settings are supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS 
CROSSOVER 


SUPPORTS CROSSOVER 

Indicates whether crossover settings are supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS 
CUSTOM1 


SUPPORTS CUSTOM1 

Indicates whether a custom effect is supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS 
CUSTOM2 


SUPPORTS CUSTOM2 

Indicates whether a custom effect is supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS 
CUSTOM3 



SUPPORTS CUSTOM3 

Indicates whether a custom effect is supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS GAIN 


SUPPORTS GAIN 

Indicates whether gain settings are supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS 
LOUDNESS 


SUPPORTS LOUDNESS 

Indicates whether loudness settings are supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS MID 


SUPPORTS MID 

Indicates whether mid settings are supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS 
MONITOR 


SUPPORTS MONITOR 

Indicates whether monitor settings are supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS 
MUTE 


SUPPORTS MUTE 

Indicates whether mute settings are supported by the connector specified. 



CAPABILITY (Mixer Command) Keyword - SUPPORTS 
PITCH 


SUPPORTS PITCH 

Indicates whether pitch settings are supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS 
REVERB 


SUPPORTS REVERB 

Indicates whether reverb settings are supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS 
STEREO ENHANCE 


SUPPORTS STEREO ENHANCE 

Indicates whether stereo enhance settings are supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS 
TREBLE 


SUPPORTS TREBLE 

Indicates whether treble settings are supported by the connector specified. 


CAPABILITY (Mixer Command) Keyword - SUPPORTS 
VOLUME 


SUPPORTS VOLUME 

Indicates whether volume settings are supported by the connector specified. 



CAPABILITY (Mixer Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


CAPABILITY (Mixer Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPABILITY (Mixer Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

CAN EJECT 

Returns FALSE. 

CAN LOCK EJECT 

Returns FALSE. 

CAN PLAY 

Returns FALSE. 

CAN PROCESS INTERNAL 

Returns FALSE. 

CAN RECORD 

Returns FALSE. 

CAN SAVE 

Returns FALSE. 

CAN STREAM 

Returns FALSE. 

CAN SET VOLUME 

Returns TRUE. 

COMPOUND DEVICE 

Returns FALSE. 


DEVICE TYPE 


Returns Ampmix. 


HAS AUDIO 

Returns TRUE. 

HAS VIDEO 

Returns FALSE. 

MESSAGE command 

Returns TRUE if the device supports the command specified by command The command can be any of the string commands such 
as OPEN, PLAY, and so on. 

PREROLL TIME 

Returns 0, indicating the preroll time is not bounded. 

PREROLL TYPE 

Returns NONE. 

USES FILES 

Returns FALSE. 

EXTENDED MIXER CONNECTOR type 

Indicates that a mixer format will be queried. The type specified must be a valid connector type. If the EXTENDED MIXER keywords 
are specified, the SUPPORTS keyword must also be specified. 

SUPPORTS AUTO LEVEL CONTROL 

Indicates whether auto-level control settings are supported by the connector specified. 

SUPPORTS BALANCE 

Indicates whether balance settings are supported by the connector specified. 

SUPPORTS BASS 

Indicates whether bass settings are supported by the connector specified. 

SUPPORTS CHORUS 

Indicates whether chorus settings are supported by the connector specified. 

SUPPORTS CROSSOVER 

Indicates whether crossover settings are supported by the connector specified. 

SUPPORTS CUSTOM1 

Indicates whether a custom effect is supported by the connector specified. 

SUPPORTS CUSTOM2 

Indicates whether a custom effect is supported by the connector specified. 

SUPPORTS CUSTOM3 

Indicates whether a custom effect is supported by the connector specified. 

SUPPORTS GAIN 

Indicates whether gain settings are supported by the connector specified. 

SUPPORTS LOUDNESS 

Indicates whether loudness settings are supported by the connector specified. 

SUPPORTS MID 

Indicates whether mid settings are supported by the connector specified. 

SUPPORTS MONITOR 

Indicates whether monitor settings are supported by the connector specified. 

SUPPORTS MUTE 

Indicates whether mute settings are supported by the connector specified. 

SUPPORTS PITCH 

Indicates whether pitch settings are supported by the connector specified. 

SUPPORTS REVERB 

Indicates whether reverb settings are supported by the connector specified. 

SUPPORTS STEREO ENHANCE 

Indicates whether stereo enhance settings are supported by the connector specified. 



SUPPORTS TREBLE 

Indicates whether treble settings are supported by the connector specified. 

SUPPORTS VOLUME 

Indicates whether volume settings are supported by the connector specified. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPABILITY (Mixer Command) - Syntax Diagram 


CAPABILITY object 

CAN EJECT 
CAN LOCK EJECT 
CAN PLAY 

CAN PROCESS INTERNAL 
CAN RECORD 
CAN SAVE 
CAN STREAM 
CAN SET VOLUME 
COMPOUND DEVICE 
DEVICE TYPE 
HAS AUDIO 
HAS VIDEO 
MESSAGE command 
PREROLL TIME 
PREROLL TYPE 
USES FILES 


EXTENDED MIXER CONNECTOR type 


SUPPORTS 

AUTO LEVEL CONTROL 

SUPPORTS 

BALANCE 

SUPPORTS 

BASS 

SUPPORTS 

CHORUS 

SUPPORTS 

CROSSOVER 

SUPPORTS 

CUSTOM1 

SUPPORTS 

CUSTOM2 

SUPPORTS 

CUSTOM3 

SUPPORTS 

GAIN 

SUPPORTS 

LOUDNESS 

SUPPORTS 

MID 

SUPPORTS 

MONITOR 

SUPPORTS 

MUTE 

SUPPORTS 

PITCH 

SUPPORTS 

REVERB 

SUPPORTS 

STEREO ENHANCE 

SUPPORTS 

TREBLE 

SUPPORTS 

VOLUME 


WAIT 

NOTIFY 


Examples 



CAPABILITY (Mixer Command) - Topics 


Select an item: 

Purpose 

Syntax Diagram 

Keywords 

Example 

Glossary 


CONNECTOR 


CONNECTOR (Mixer Command) - Example 


The following command returns TRUE. 

connector wave query type amp stream wait 


CONNECTOR (Mixer Command) - Purpose 


The CONNECTOR command enables, disables, or queries the status of connectors on a device. 


CONNECTOR (Mixer Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


CONNECTOR (Mixer Command) Keyword - ENABLE 


ENABLE 

Enables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 


also be specified. 


CONNECTOR (Mixer Command) Keyword - DISABLE 


DISABLE 

Disables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 


CONNECTOR (Mixer Command) Keyword - QUERY 


QUERY 

Queries the status of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled 
respectively. Use of this option requires that the NUMBER or TYPE keywords, or both also be specified. 


CONNECTOR (Mixer Command) Keyword - NUMBER 
connector number 


NUMBER connectornumber 

Indicates the connector number on which to perform the requested action. If this item is omitted, then the first connector is assumed. 
If the TYPE keyword is included, then the connector number is interpreted as a relative offset within the specified connector type. 


CONNECTOR (Mixer Command) Keyword - TYPE 
connector_type 

TYPE connector type 

Indicates the type of connector to which the requested action applies. The following connector types are supported by this device, 
amp stream 

Digital input or output for the audio amplifier/mixer. This connector is always enabled. 

line in 

The line input connector. This connector is usually attached to the line out connector of another device such as a 
tape player or other audio input source. 

microphone 

The microphone connector. This connector is usually attached to a microphone for live recording or voice 
annotation. 

line out 

The line output connector. This connector is usually attached to the line in connector of another device such as a 
tape recorder or other audio device. 



speakers 


The speakers connector. This connector is usually attached to a pair of external or internal speakers. 


headphones 


The headphones connector. This connector is usually attached to a pair of headphones. 


CONNECTOR (Mixer Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CONNECTOR (Mixer Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTOR (Mixer Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

ENABLE 

Enables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 

DISABLE 

Disables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 

QUERY 

Queries the status of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled 
respectively. Use of this option requires that the NUMBER or TYPE keywords, or both also be specified. 

NUMBER connectornumber 

Indicates the connector number on which to perform the requested action. If this item is omitted, then the first connector is assumed. 
If the TYPE keyword is included, then the connector number is interpreted as a relative offset within the specified connector type. 

TYPE connector type 

Indicates the type of connector to which the requested action applies. The following connector types are supported by this device, 
amp stream 

Digital input or output for the audio amplifier/mixer. This connector is always enabled. 


line in 

The line input connector. This connector is usually attached to the line out connector of another device such as a 
tape player or other audio input source. 

microphone 

The microphone connector. This connector is usually attached to a microphone for live recording or voice 
annotation. 

line out 

The line output connector. This connector is usually attached to the line in connector of another device such as a 
tape recorder or other audio device. 

speakers 

The speakers connector. This connector is usually attached to a pair of external or internal speakers. 

headphones 

The headphones connector. This connector is usually attached to a pair of headphones. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTOR (Mixer Command) - Syntax Diagram 


CONNECTOR object 


ENABLE 

DISABLE 

QUERY 


NUMBER connector_number 

TYPE connector_type WAIT 

NOTIFY 


Examples 


CONNECTOR (Mixer Command) - Topics 


Select an item: 

Purpose 

Syntax Diagram 

Keywords 

Example 

Glossary 


MIXNOTIFY 



MIXNOTIFY (Mixer Command) - Example 


mixnotify ampmixOl on 


MIXNOTIFY (Mixer Command) - Purpose 


The MIXNOTIFY command notifies an application when a mixer attribute (such as treble, bass, and so on) changes. 


MIXNOTIFY (Mixer Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


MIXNOTIFY (Mixer Command) Keyword - ON 


ON 

Turns mixer notifications on. 


MIXNOTIFY (Mixer Command) Keyword - OFF 


OFF 

Turns mixer notifications off. 


MIXNOTIFY (Mixer Command) Keyword - WAIT 



WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


MIXNOTIFY (Mixer Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


MIXNOTIFY (Mixer Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


ON 

Turns mixer notifications on. 

OFF 

Turns mixer notifications off. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


MIXNOTIFY (Mixer Command) - Syntax Diagram 


MIXNOTIFY object ON 

OFF WAIT 

NOTIFY 


Examples 



MIXNOTIFY (Mixer Command) - Topics 


Select an item: 

Purpose 

Syntax Diagram 

Keywords 

Example 

Glossary 


SET 


SET (Mixer Command) - Example 


set ampmixOl audio gain 80 wait 


SET (Mixer Command) - Purpose 


The SET command sets various control items for the audio amplifier mixer. 


SET (Mixer Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following 

• Device type 

• Device name 

• Filename 

• Alias 


SET (Mixer Command) Keyword - AUDIO 


AUDIO 


The audio attributes of the device context specified by the ALL, LEFT, RIGHT, OVER, and VOLUME keywords. 


SET (Mixer Command) Keyword - ALL 


ALL 

Applies to both or all channels (default). 
Specify ON or OFF with the ALL keyword. 


SET (Mixer Command) Keyword - ON 


ON 

Enable audio output. 


SET (Mixer Command) Keyword - OFF 


OFF 

Disable audio output. 


SET (Mixer Command) Keyword - LEFT 


LEFT 

Applies to left channel. 

Specify ON or OFF with the LEFT keyword. 


SET (Mixer Command) Keyword - ON 


ON 

Enable audio output to the left audio channel. 


SET (Mixer Command) Keyword - OFF 



OFF 


Disable audio output to the left audio channel. 


SET (Mixer Command) Keyword - RIGHT 

RIGHT 

Applies to right channel. 

Specify ON or OFF with the RIGFIT keyword. 


SET (Mixer Command) Keyword - ON 


ON 

Enable audio output to the right audio channel. 


SET (Mixer Command) Keyword - OFF 


OFF 

Disable audio output to the right audio channel. 


SET (Mixer Command) Keyword - BASS level 


BASS level 

Sets the bass level as a percentage of the maximum achievable effect. The effect applies to the final output mix. Any specification of 
a channel is ignored. 


SET (Mixer Command) Keyword - TREBLE level 


TREBLE level 

Sets the mixer-channel treble level as a percentage of the maximum achievable effect. The effect applies to the final output mix. Any 
specification of a channel is ignored. 



SET (Mixer Command) Keyword - BALANCE level 


BALANCE level 

Sets the balance level. Zero is defined as full left balance while one hundred is defined as full right balance. This value is ignored for 
monaural channels. This effect applies to the final output mix. Any specification of a channel is ignored. 


SET (Mixer Command) Keyword - PITCH level 


PITCH level 

Sets the pitch as a percentage of the maximum achievable effect. This effect applies to the final output mix. Any specification of a 
channel is ignored. 


SET (Mixer Command) Keyword - GAIN level 


GAIN level 

Sets the gain as a percentage of the maximum achievable effect for the currently selected input. 


SET (Mixer Command) Keyword - MONITOR 


MONITOR 

Sets the amplifier mixer device to monitor, or not to monitor, the input signal from one device while the output of another device is 
being recorded. This option should be used along with the ON and OFF keywords. 

Specify ON or OFF with the MONITOR keyword. 


SET (Mixer Command) Keyword - ON 


ON 

Enables monitoring of the input signal. 


SET (Mixer Command) Keyword - OFF 



OFF 


Disables monitoring of the input signal. 


SET (Mixer Command) Keyword - OVER milliseconds 


OVER milliseconds 

Apply the change over the specified time period (fade). 


SET (Mixer Command) Keyword - VOLUME level 


VOLUME level 

Sets the mixer-channel volume level as a percentage of the maximum achievable effect. The precise channel is specified by using 
the ALL, LEFT, or RIGHT keywords. 


SET (Mixer Command) Keyword - CONNECTOR type 


CONNECTOR type 

Specifies one of the following connector types for which the settings are to apply. 

• amp stream 

• audio in 

• audio out 

• headphones 

• internalaudio 

• microphone 

• midi in 

• midi out 

• midi stream 

• line in 

• line out 

• null 

• phone set 

• phone line 

• speakers 

• universal 


SET (Mixer Command) Keyword - MIXER AUTO LEVEL 
CONTROL level 


MIXER AUTO LEVEL CONTROL level 



Sets the auto-level control setting for the specified connector as a percentage (0-1 00). 


SET (Mixer Command) Keyword - MIXER BALANCE level 


MIXER BALANCE level 

Sets the balance setting for the specified connector as a percentage (0-100). 


SET (Mixer Command) Keyword - MIXER BASS level 


MIXER BASS level 

Sets the bass setting for the specified connector as a percentage (0-100). 


SET (Mixer Command) Keyword - MIXER CHORUS level 


MIXER CHORUS level 

Sets the chorus setting for the specified connector as a percentage (0-1 00). 


SET (Mixer Command) Keyword - MIXER CROSSOVER level 


MIXER CROSSOVER level 

Sets the crossover setting for the specified connector as a percentage (0-100). 


SET (Mixer Command) Keyword - MIXER CUSTOM1 level 


MIXER CUSTOM1 level 

Sets the custom effect setting for the specified connector as a percentage (0-100). 


SET (Mixer Command) Keyword - MIXER CUSTOM2 level 



MIXER CUST0M2 level 

Sets the custom effect setting for the specified connector as a percentage (0-100). 


SET (Mixer Command) Keyword - MIXER CUSTOM3 level 


MIXER CUSTOM3 level 

Sets the custom effect setting for the specified connector as a percentage (0-100). 


SET (Mixer Command) Keyword - MIXER GAIN level 


MIXER GAIN level 

Sets the gain setting for the specified connector as a percentage (0-1 00). 


SET (Mixer Command) Keyword - MIXER LOUDNESS level 


MIXER LOUDNESS level 

Sets the loudness setting for the specified connector as a percentage (0-100). 


SET (Mixer Command) Keyword - MIXER MID level 


MIXER MID level 

Sets the mid setting for the specified connector as a percentage (0-1 00). 


SET (Mixer Command) Keyword - MIXER MONITOR level 


MIXER MONITOR level 

Sets the monitor setting for the specified connector as a percentage (0-1 00). 


SET (Mixer Command) Keyword - MIXER MUTE 



MIXER MUTE 

Sets the specified connector to mute. 


SET (Mixer Command) Keyword - MIXER PITCH level 


MIXER PITCH level 

Sets the pitch setting for the specified connector as a percentage (0-100). 


SET (Mixer Command) Keyword - MIXER REVERB level 


MIXER REVERB level 

Sets the reverb setting for the specified connector as a percentage (0-100). 


SET (Mixer Command) Keyword - MIXER STEREO 
ENHANCE level 


MIXER STEREO ENHANCE level 

Sets the stereo enhancement setting for the specified connector as a percentage (0-100). 


SET (Mixer Command) Keyword - MIXER TREBLE level 


MIXER TREBLE level 

Sets the treble setting for the specified connector as a percentage (0-100). 


SET (Mixer Command) Keyword - MIXER VOLUME level 


MIXER VOLUME level 

Sets the volume setting for the specified connector as a percentage (0-100). 


SET (Mixer Command) Keyword - WAIT 



WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SET (Mixer Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SET (Mixer Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


AUDIO 


The audio attributes of the device context specified by the ALL, LEFT, RIGFIT, OVER, and VOLUME keywords. 


ALL 


LEFT 


RIGHT 


Applies to both or all channels (default). 
Specify ON or OFF with the ALL keyword. 


ON 

OFF 


Enable audio output. 
Disable audio output. 


Applies to left channel. 

Specify ON or OFF with the LEFT keyword. 


ON 

OFF 


Enable audio output to the left audio channel. 
Disable audio output to the left audio channel. 


Applies to right channel. 

Specify ON or OFF with the RIGFIT keyword. 

ON 

Enable audio output to the right audio channel. 


OFF 


Disable audio output to the right audio channel. 


BASS level 

Sets the bass level as a percentage of the maximum achievable effect. The effect applies to the final output mix. 
Any specification of a channel is ignored. 


TREBLE level 

Sets the mixer-channel treble level as a percentage of the maximum achievable effect. The effect applies to the 
final output mix. Any specification of a channel is ignored. 


BALANCE level 

Sets the balance level. Zero is defined as full left balance while one hundred is defined as full right balance. This 
value is ignored for monaural channels. This effect applies to the final output mix. Any specification of a channel 
ignored. 


PITCH level 


GAIN level 


MONITOR 


Sets the pitch as a percentage of the maximum achievable effect. This effect applies to the final output mix. Any 
specification of a channel is ignored. 


Sets the gain as a percentage of the maximum achievable effect for the currently selected input. 


Sets the amplifier mixer device to monitor, or not to monitor, the input signal from one device while the output of 
another device is being recorded. This option should be used along with the ON and OFF keywords. 

Specify ON or OFF with the MONITOR keyword. 


ON 


Enables monitoring of the input signal. 


OFF 


Disables monitoring of the input signal. 


OVER milliseconds 

Apply the change over the specified time period (fade). 


VOLUME level 

Sets the mixer-channel volume level as a percentage of the maximum achievable effect. The precise channel is 
specified by using the ALL, LEFT, or RIGHT keywords. 

CONNECTOR type 

Specifies one of the following connector types for which the settings are to apply. 

• amp stream 

• audio in 

• audio out 

• headphones 

• internalaudio 

• microphone 

• midi in 

• midi out 

• midi stream 

• line in 

• line out 

• null 

• phone set 

• phone line 

• speakers 

• universal 

MIXER AUTO LEVEL CONTROL level 

Sets the auto-level control setting for the specified connector as a percentage (0-1 00). 

MIXER BALANCE level 

Sets the balance setting for the specified connector as a percentage (0-1 00). 

MIXER BASS level 

Sets the bass setting for the specified connector as a percentage (0-100). 

MIXER CHORUS level 

Sets the chorus setting for the specified connector as a percentage (0-1 00). 


MIXER CROSSOVER level 



Sets the crossover setting for the specified connector as a percentage (0-100). 

MIXER CUSTOM1 level 

Sets the custom effect setting for the specified connector as a percentage (0-100). 

MIXER CUSTOM2 level 

Sets the custom effect setting for the specified connector as a percentage (0-100). 

MIXER CUSTOM3 level 

Sets the custom effect setting for the specified connector as a percentage (0-100). 

MIXER GAIN level 

Sets the gain setting for the specified connector as a percentage (0-1 00). 

MIXER LOUDNESS level 

Sets the loudness setting for the specified connector as a percentage (0-100). 

MIXER MID level 

Sets the mid setting for the specified connector as a percentage (0-1 00). 

MIXER MONITOR level 

Sets the monitor setting for the specified connector as a percentage (0-1 00). 

MIXER MUTE 

Sets the specified connector to mute. 

MIXER PITCH level 

Sets the pitch setting for the specified connector as a percentage (0-100). 

MIXER REVERB level 

Sets the reverb setting for the specified connector as a percentage (0-100). 

MIXER STEREO ENHANCE level 

Sets the stereo enhancement setting for the specified connector as a percentage (0-1 00). 

MIXER TREBLE level 

Sets the treble setting for the specified connector as a percentage (0-100). 

MIXER VOLUME level 

Sets the volume setting for the specified connector as a percentage (0-100). 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SET (Mixer Command) - Syntax Diagram 


SET object 


AUDIO 


ALL ON 

OFF 

LEFT ON 

OFF 

RIGHT ON 

OFF 

BASS level 
TREBLE level 
BALANCE level 
PITCH level 
GAIN level 
MONITOR ON 


OFF 

OVER milliseconds 
VOLUME level 


CONNECTOR type MIXER AUTO LEVEL CONTROL level 

MIXER BASS level 
MIXER BALANCE level 
MIXER CHORUS level 
MIXER CROSSOVER level 
MIXER CUSTOM1 level 
MIXER CUSTOM2 level 
MIXER CUSTOM3 level 
MIXER GAIN level 
MIXER LOUDNESS level 
MIXER MID level 
MIXER MONITOR level 
MIXER MUTE 
MIXER PITCH level 
MIXER REVERB level 
MIXER STEREO ENHANCE level 
MIXER TREBLE level 
MIXER VOLUME level 


Examples 


SET (Mixer Command) - Topics 
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Syntax Diagram 

Keywords 

Example 
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STATUS 


STATUS (Mixer Command) - Example 


status ampmixOl balance wait 


STATUS (Mixer Command) - Purpose 


WAIT 

NOTIFY 


The STATUS command obtains status information for the device. 



STATUS (Mixer Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


STATUS (Mixer Command) Keyword - AUDIO CHANNEL 
value 


AUDIO CHANNEL value 

Must specify all, left, right, or a number. Returns TRUE or FALSE to indicate whether the channel is enabled or disabled, 
respectively. 


STATUS (Mixer Command) Keyword - BASS 


BASS 

Returns the current bass setting as a percentage of the maximum achievable effect. 


STATUS (Mixer Command) Keyword - BALANCE 


BALANCE 

Returns the current balance setting where zero is defined as full left balance and one hundred is defined as full right balance. 


STATUS (Mixer Command) Keyword - CURRENT TRACK 


CURRENT TRACK 

Returns the current function. The amplifier mixer device always returns 1 . 


STATUS (Mixer Command) Keyword - GAIN 



GAIN 


Returns the current gain setting as a percentage of the maximum achievable effect. 


STATUS (Mixer Command) Keyword - LENGTH 


LENGTH 

Returns the total length of the segment. The amplifier mixer device does not support this function. 


STATUS (Mixer Command) Keyword - LENGTH TRACK 
number 


LENGTH TRACK number 

Returns the length of the track specified by number. The amplifier mixer device does not support this function. 


STATUS (Mixer Command) Keyword - MONITOR 


MONITOR 

Returns whether on not the amplifier mixer device is monitoring the input signal from one device while the output of another device 
being recorded. Either TRUE or FALSE will be returned. 


STATUS (Mixer Command) Keyword - NUMBER OF 
TRACKS 


NUMBER OF TRACKS 

Returns the number of tracks on the media. The amplifier mixer device does not support this function. 


STATUS (Mixer Command) Keyword - PITCH 


PITCH 


Returns the current pitch setting as a percentage of the maximum achievable effect. 



STATUS (Mixer Command) Keyword - POSITION 


POSITION 

Returns the current position. The amplifier mixer device does not support this function. 


STATUS (Mixer Command) Keyword - POSITION IN TRACK 


POSITION IN TRACK 

Returns the current position relative to the beginning of the track. The amplifier mixer device does not support this function. 


STATUS (Mixer Command) Keyword - POSITION TRACK 
number 


POSITION TRACK number 

Returns the position of the start of the track specified by number. The amplifier mixer device does not support this function. 


STATUS (Mixer Command) Keyword - SPEED FORMAT 


SPEED FORMAT 

Returns the current speed format. The amplifier mixer device does not support this function. 


STATUS (Mixer Command) Keyword - TIME FORMAT 


TIME FORMAT 

Returns the current time format. The amplifier mixer device does not support this function. 


STATUS (Mixer Command) Keyword - TREBLE 


TREBLE 



Returns the current treble setting as a percentage of the maximum achievable effect. 


STATUS (Mixer Command) Keyword - VOLUME 


VOLUME 

Returns the current volume setting. The volume is returned as a string in the format ieftr/ght where /eft and right are percentages of 
the maximum achievable effect for the left and right channels respectively. Leading zeros are suppressed for the volume level in each 
channel. 


STATUS (Mixer Command) Keyword - CONNECTOR type 

CONNECTOR type 

Specifies the connector that status information is desired from. The connector specified must be a valid connector. 


STATUS (Mixer Command) Keyword - AUTO LEVEL 
CONTROL 


AUTO LEVEL CONTROL 

Returns the auto-level control setting for the desired connector. 


STATUS (Mixer Command) Keyword - BALANCE 


BALANCE 

Returns the balance setting for the desired connector. 


STATUS (Mixer Command) Keyword - BASS 


BASS 

Returns the bass setting for the desired connector. 


STATUS (Mixer Command) Keyword - CHORUS 



CHORUS 

Returns the chorus setting for the desired connector. 


STATUS (Mixer Command) Keyword - CROSSOVER 


CROSSOVER 

Returns the crossover setting for the desired connector. 


STATUS (Mixer Command) Keyword - CUSTOM1 


CUSTOM1 

Returns the custom effect setting for the desired connector. 


STATUS (Mixer Command) Keyword - CUSTOM2 


CUSTOM2 

Returns the custom effect setting for the desired connector. 


STATUS (Mixer Command) Keyword - CUSTOM3 


CUSTOM3 

Returns the custom effect setting for the desired connector. 


STATUS (Mixer Command) Keyword - GAIN 


GAIN 

Returns the gain setting for the desired connector. 


STATUS (Mixer Command) Keyword - LOUDNESS 



LOUDNESS 

Returns the loudness setting for the desired connector. 


STATUS (Mixer Command) Keyword - MID 


MID 

Returns the mid setting for the desired connector. 


STATUS (Mixer Command) Keyword - MONITOR 


MONITOR 

Returns the monitor setting for the desired connector. 


STATUS (Mixer Command) Keyword - MUTE 


MUTE 

Returns the mute setting for the desired connector. 


STATUS (Mixer Command) Keyword - PITCH 


PITCH 

Returns the pitch setting for the desired connector. 


STATUS (Mixer Command) Keyword - REVERB 


REVERB 

Returns the reverb setting for the desired connector. 


STATUS (Mixer Command) Keyword - TREBLE 



TREBLE 

Returns the treble setting for the desired connector. 


STATUS (Mixer Command) Keyword - VOLUME 

VOLUME 

Returns the volume setting for the desired connector. 


STATUS (Mixer Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified to receive return string information. 


STATUS (Mixer Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (Mixer Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

AUDIO CHANNEL value 

Must specify all, left, right, or a number. Returns TRUE or FALSE to indicate whether the channel is enabled or disabled, 
respectively. 


BASS 

Returns the current bass setting as a percentage of the maximum achievable effect. 

BALANCE 

Returns the current balance setting where zero is defined as full left balance and one hundred is defined as full right balance. 


CURRENT TRACK 


Returns the current function. The amplifier mixer device always returns 1 . 

GAIN 

Returns the current gain setting as a percentage of the maximum achievable effect. 

LENGTH 

Returns the total length of the segment. The amplifier mixer device does not support this function. 

LENGTH TRACK number 

Returns the length of the track specified by number. The amplifier mixer device does not support this function. 

MONITOR 

Returns whether on not the amplifier mixer device is monitoring the input signal from one device while the output of another device is 
being recorded. Either TRUE or FALSE will be returned. 

NUMBER OF TRACKS 

Returns the number of tracks on the media. The amplifier mixer device does not support this function. 

PITCH 

Returns the current pitch setting as a percentage of the maximum achievable effect. 

POSITION 

Returns the current position. The amplifier mixer device does not support this function. 

POSITION IN TRACK 

Returns the current position relative to the beginning of the track. The amplifier mixer device does not support this function. 

POSITION TRACK number 

Returns the position of the start of the track specified by number. The amplifier mixer device does not support this function. 

SPEED FORMAT 

Returns the current speed format. The amplifier mixer device does not support this function. 

TIME FORMAT 

Returns the current time format. The amplifier mixer device does not support this function. 

TREBLE 

Returns the current treble setting as a percentage of the maximum achievable effect. 

VOLUME 

Returns the current volume setting. The volume is returned as a string in the format /eftright where /eft and right are percentages of 
the maximum achievable effect for the left and right channels respectively. Leading zeros are suppressed for the volume level in each 
channel. 

CONNECTOR type 

Specifies the connector that status information is desired from. The connector specified must be a valid connector. 

AUTO LEVEL CONTROL 

Returns the auto-level control setting for the desired connector. 

BALANCE 

Returns the balance setting for the desired connector. 

BASS 

Returns the bass setting for the desired connector. 

CHORUS 

Returns the chorus setting for the desired connector. 

CROSSOVER 

Returns the crossover setting for the desired connector. 

CUSTOM1 

Returns the custom effect setting for the desired connector. 

CUSTOM2 

Returns the custom effect setting for the desired connector. 

CUSTOM3 

Returns the custom effect setting for the desired connector. 

GAIN 

Returns the gain setting for the desired connector. 



LOUDNESS 

Returns the loudness setting for the desired connector. 

MID 

Returns the mid setting for the desired connector. 

MONITOR 

Returns the monitor setting for the desired connector. 

MUTE 

Returns the mute setting for the desired connector. 

PITCH 

Returns the pitch setting for the desired connector. 

REVERB 

Returns the reverb setting for the desired connector. 

TREBLE 

Returns the treble setting for the desired connector. 

VOLUME 

Returns the volume setting for the desired connector. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (Mixer Command) - Syntax Diagram 


STATUS object 

AUDIO CHANNEL value 

BASS 

BALANCE 

CURRENT TRACK 

GAIN 

LENGTH 

LENGTH TRACK number 
MONITOR 

NUMBER OF TRACKS 

PITCH 

POSITION 

POSITION IN TRACK 

POSITION TRACK number 

SPEED FORMAT 

TIME FORMAT 

TREBLE 

VOLUME 


CONNECTOR type AUTO LEVEL CONTROL WAIT 

BALANCE NOTIFY 
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CUSTOM2 
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STATUS (Mixer Command) - Topics 
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CD Audio Commands 


The CD audio device supports the device-type specific command, CUE, and extensions to the following basic and required commands: 

• CAPABILITY 

• CONNECTOR 

• CUE 
INFO 

• PLAY 
SET 

• STATUS 


CAPABILITY 


CAPABILITY (CD Audio Command) - Example 

The following command returns FALSE. 

capability cdaudio can record wait 


CAPABILITY (CD Audio Command) - Purpose 



The CAPABILITY command requests additional information about the capabilities of the CD device. 


CAPABILITY (CD Audio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CAPABILITY (CD Audio Command) Keyword - CAN EJECT 


CAN EJECT 

Returns TRUE if the CD audio device can eject the media. 


CAPABILITY (CD Audio Command) Keyword - CAN 
LOCKEJECT 


CAN LOCKEJECT 

Returns TRUE if the device can disable manual ejection of the media. 


CAPABILITY (CD Audio Command) Keyword - CAN PLAY 


CAN PLAY 

Returns TRUE if the CD audio device can play the media. 


CAPABILITY (CD Audio Command) Keyword - CAN 
PROCESS INTERNAL 


CAN PROCESS INTERNAL 

Returns TRUE if the device can internally process digital data with an internal digital to analog converter (DAC). 



CAPABILITY (CD Audio Command) Keyword - CAN 
RECORD 


CAN RECORD 

Returns FALSE. CD audio devices cannot record. 


CAPABILITY (CD Audio Command) Keyword - CAN SAVE 


CAN SAVE 

Returns FALSE. CD audio devices cannot save data. 


CAPABILITY (CD Audio Command) Keyword - CAN 
SETVOLUME 


CAN SETVOLUME 

Returns TRUE if the device supports software control of volume level. 


CAPABILITY (CD Audio Command) Keyword - CAN STREAM 


CAN STREAM 

Returns TRUE if the device can continuously transfer digital data to or from another device. The source or destination of the data is 
determined by the device context connection. 


CAPABILITY (CD Audio Command) Keyword - COMPOUND 
DEVICE 


COMPOUND DEVICE 

Returns FALSE. CD audio devices are simple devices. 



CAPABILITY (CD Audio Command) Keyword - DEVICE TYPE 


DEVICE TYPE 

Returns CDaudio. 


CAPABILITY (CD Audio Command) Keyword - HAS AUDIO 


HAS AUDIO 

Returns TRUE. 


CAPABILITY (CD Audio Command) Keyword - HAS VIDEO 


HAS VIDEO 

Returns FALSE. CD audio devices do not support video. 


CAPABILITY (CD Audio Command) Keyword - PREROLL 
TIME 


PREROLL TIME 

Returns 0, indicating the preroll time is not bounded. 


CAPABILITY (CD Audio Command) Keyword - PREROLL 
TYPE 


PREROLL TYPE 

Returns the preroll characteristics of the device: Returns NONE. 


CAPABILITY (CD Audio Command) Keyword - USES FILES 


USES FILES 



Returns FALSE. CD audio devices do not use files. 


CAPABILITY (CD Audio Command) Keyword - WAIT 


WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


CAPABILITY (CD Audio Command) Keyword - NOTIFY 


NOTIFY 


The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CAN EJECT 

Returns TRUE if the CD audio device can eject the media. 

CAN LOCKEJECT 

Returns TRUE if the device can disable manual ejection of the media. 

CAN PLAY 

Returns TRUE if the CD audio device can play the media. 

CAN PROCESS INTERNAL 

Returns TRUE if the device can internally process digital data with an internal digital to analog converter (DAC). 

CAN RECORD 

Returns FALSE. CD audio devices cannot record. 

CAN SAVE 

Returns FALSE. CD audio devices cannot save data. 

CAN SETVOLUME 

Returns TRUE if the device supports software control of volume level. 

CAN STREAM 

Returns TRUE if the device can continuously transfer digital data to or from another device. The source or destination of the data is 
determined by the device context connection. 

COMPOUND DEVICE 

Returns FALSE. CD audio devices are simple devices. 



object 


Object associated with this media control interface command. The object can be one of the following: 


Device type 
Device name 
Filename 
Alias 


DEVICE TYPE 

Returns CDaudio. 

HAS AUDIO 

Returns TRUE. 

HAS VIDEO 

Returns FALSE. CD audio devices do not support video. 

PREROLL TIME 

Returns 0, indicating the preroll time is not bounded. 

PREROLL TYPE 

Returns the preroll characteristics of the device: Returns NONE. 

USES FILES 

Returns FALSE. CD audio devices do not use files. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPABILITY (CD Audio Command) - Syntax Diagram 
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CAPABILITY 


object 
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CAN PLAY 

CAN PROCESS INTERNAL 
CAN RECORD 
CAN SAVE 
CAN STREAM 
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WAIT 
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CONNECTOR 


CONNECTOR (CD Audio Command) - Example 


(This example assumes the device can stream.) 

open cdaudio alias cdaud shareable wait 
connector cdaud enable type CD stream wait 


CONNECTOR (CD Audio Command) - Purpose 


The CONNECTOR command enables, disables, or queries the status of connectors on a device. 


CONNECTOR (CD Audio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CONNECTOR (CD Audio Command) Keyword - ENABLE 


ENABLE 

Enables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 


CONNECTOR (CD Audio Command) Keyword - DISABLE 


DISABLE 

Disables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 



also be specified. 


CONNECTOR (CD Audio Command) Keyword - QUERY 


QUERY 

Queries the status of the indicated connector. The return value will be either "true" or "false" to indicate enabled or disabled. Using 
this option requires that the NUMBER or TYPE keywords, or both also be specified. 


CONNECTOR (CD Audio Command) Keyword - NUMBER 
connector number 


NUMBER connectornumber 

Indicates the connector number on which to perform the requested action. If this keyword is omitted, then the first connector is 
assumed. If the TYPE keyword is included, the connector number is interpreted as a relative offset within the specified connector 
type. 


CONNECTOR (CD Audio Command) Keyword - TYPE 
connector_type 


TYPE connector type 

Indicates the type of connector to which the requested action applies. The following connector types are supported by this device: 

CD stream 

Digital output for CD devices. If this connector is enabled and the device has returned TRUE to the CAPABILITY 
object CAN STREAM WAIT command, the CD device will stream digital data to its associated amp/mixer. 

headphones 

The headphones connector. This connector is usually attached to a pair of headphones on the CD device itself. 


CONNECTOR (CD Audio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CONNECTOR (CD Audio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTOR (CD Audio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

ENABLE 

Enables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 

DISABLE 

Disables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 

QUERY 

Queries the status of the indicated connector. The return value will be either "true" or "false" to indicate enabled or disabled. Using 
this option requires that the NUMBER or TYPE keywords, or both also be specified. 

NUMBER connector number 

Indicates the connector number on which to perform the requested action. If this keyword is omitted, then the first connector is 
assumed. If the TYPE keyword is included, the connector number is interpreted as a relative offset within the specified connector 
type. 

TYPE connector type 

Indicates the type of connector to which the requested action applies. The following connector types are supported by this device: 

CD stream 

Digital output for CD devices. If this connector is enabled and the device has returned TRUE to the CAPABILITY 
object CAN STREAM WAIT command, the CD device will stream digital data to its associated amp/mixer. 

headphones 

The headphones connector. This connector is usually attached to a pair of headphones on the CD device itself. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


CONNECTOR (CD Audio Command) - Syntax Diagram 
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CONNECTOR (CD Audio Command) - Topics 
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CUE 


CUE (CD Audio Command) - Example 

cue cdaudio output wait 


CUE (CD Audio Command) - Purpose 


The CUE command prepares for playback. The CUE command does not have to be issued prior to playback; however, depending on the 
device, it might reduce the delay associated with the PLAY command. 

The CUE command is not related to the SETCUEPOINT command. 


CUE (CD Audio Command) Keyword - object 


object 


Object associated with this media control interface command. The object can be one of the following: 



Device type 
Device name 
Filename 
Alias 


CUE (CD Audio Command) Keyword - OUTPUT 


OUTPUT 

Prepares the device for playback. 


CUE (CD Audio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CUE (CD Audio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CUE (CD Audio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

OUTPUT 

Prepares the device for playback. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CUE (CD Audio Command) - Syntax Diagram 


CUE object 


OUTPUT 
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NOTIFY 


Examples 


CUE (CD Audio Command) - Topics 
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INFO 


INFO (CD Audio Command) - Example 


info cdaudio product wait 


INFO (CD Audio Command) - Purpose 


The INFO command fills a user-supplied buffer with information. 


INFO (CD Audio Command) Keyword - object 



object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


INFO (CD Audio Command) Keyword - ID 


ID 

Returns the disc ID if the device supports this function, otherwise, it returns 0. The value returned is a binary value. 


INFO (CD Audio Command) Keyword - PRODUCT 


PRODUCT 

Returns the product name and model of the current audio device. 


INFO (CD Audio Command) Keyword - UPC 


UPC 

Returns the disc UPC code (serial number) if the device supports this function, otherwise, it returns 0. The value returned is a binary 
value. 


INFO (CD Audio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


INFO (CD Audio Command) Keyword - NOTIFY 


NOTIFY 



The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


INFO (CD Audio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

ID 

Returns the disc ID if the device supports this function, otherwise, it returns 0. The value returned is a binary value. 

PRODUCT 

Returns the product name and model of the current audio device. 

UPC 

Returns the disc UPC code (serial number) if the device supports this function, otherwise, it returns 0. The value returned is a binary 
value. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


INFO (CD Audio Command) - Syntax Diagram 


INFO object 
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INFO (CD Audio Command) - Topics 
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PLAY 


PLAY (CD Audio Command) - Example 


play cdaudio from 10000 to 30000 wait 


PLAY (CD Audio Command) - Purpose 


The PLAY command starts playing audio. 


PLAY (CD Audio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


PLAY (CD Audio Command) Keyword - FROM pos 


FROM pos 

The position to start playing. If FROM is omitted, the device starts playing at the current position. If the FROM position is greater than 
the end position of the disc, or if the FROM position is greater than the TO position, an error is returned. 


PLAY (CD Audio Command) Keyword - TO pos 


TO pos 



The position to stop playing. If TO is omitted, play stops at the end of the disc. If the TO position is greater than the length of the disc, 
it receives an OUT OF RANGE error. 


PLAY (CD Audio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


PLAY (CD Audio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


PLAY (CD Audio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

FROM pos 

The position to start playing. If FROM is omitted, the device starts playing at the current position. If the FROM position is greater than 
the end position of the disc, or if the FROM position is greater than the TO position, an error is returned. 

TO pos 

The position to stop playing. If TO is omitted, play stops at the end of the disc. If the TO position is greater than the length of the disc, 
it receives an OUT OF RANGE error. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


PLAY (CD Audio Command) - Syntax Diagram 
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PLAY (CD Audio Command) - Topics 
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SET 


SET (CD Audio Command) - Example 


set cdaudio time format tmsf wait 


SET (CD Audio Command) - Purpose 


The SET command sets the various control items. 


SET (CD Audio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following 


Device type 



Device name 

Filename 

Alias 


SET (CD Audio Command) Keyword - AUDIO 


AUDIO 

Sets the audio attributes of the device context specified by the ALL, LEFT, RIGFIT, OVER, and VOLUME keywords. 


SET (CD Audio Command) Keyword - ALL 


ALL 

Applies to both/all channels (default). 
Specify ON or OFF with the ALL keyword. 


SET (CD Audio Command) Keyword - ON 


ON 

Enables audio output. 


SET (CD Audio Command) Keyword - OFF 


OFF 

Disables audio output. 


SET (CD Audio Command) Keyword - LEFT 


LEFT 

Applies to left channel. 

Specify ON or OFF with the LEFT keyword. 



SET (CD Audio Command) Keyword - ON 


ON 

Enables audio output to the left channel. 


SET (CD Audio Command) Keyword - OFF 


OFF 

Disables audio output to the left channel. 


SET (CD Audio Command) Keyword - RIGFIT 


RIGHT 

Applies to right channel. 

Specify ON or OFF with the RIGFIT keyword. 


SET (CD Audio Command) Keyword - ON 


ON 

Enables audio output to the right channel. 


SET (CD Audio Command) Keyword - OFF 


OFF 

Disables audio output to the right channel. 


SET (CD Audio Command) Keyword - OVER milliseconds 


OVER milliseconds 

Applies the change over the specified time period (fade). 



SET (CD Audio Command) Keyword - VOLUME percentage 


VOLUME percentage 

Sets the device/mixer channel volume level. 


SET (CD Audio Command) Keyword - DOOR CLOSED 


DOOR CLOSED 

Retracts the tray and closes the door, if possible. 


SET (CD Audio Command) Keyword - DOOR LOCKED 


DOOR LOCKED 

Locks the media cover on the device (if any). This disables manual ejection of the media from the device. 


SET (CD Audio Command) Keyword - DOOR OPEN 


DOOR OPEN 

Opens the door and ejects the tray, if possible. This enables manual ejection of the media from the device. 


SET (CD Audio Command) Keyword - DOOR UNLOCKED 


DOOR UNLOCKED 

Unlocks the media cover on the device (if any). This enables manual ejection of the media from the device. 


SET (CD Audio Command) Keyword - TIME FORMAT 
MILLISECONDS 


TIME FORMAT MILLISECONDS 



Sets the time format to milliseconds. All position information is in this format after this command. You can abbreviate as ms. 


SET (CD Audio Command) Keyword - TIME FORMAT 
MMTIME 


TIME FORMAT MMTIME 

Sets the time format to MMTIME. 


SET (CD Audio Command) Keyword - TIME FORMAT MSF 


TIME FORMAT MSF 

Sets the time format to mm.ss.ff , where mm is minutes, ss is seconds, and ff is frames. All position information is in this format 
after this command. The ff input can be omitted if it is 0; ss can be omitted if both ss and ff are 0. These fields have the following 
maximum values: 


Minutes ( mm ) 

99 


Seconds (ss) 

59 


Frames (ff) 

74 


SET (CD Audio Command) Keyword 

-TIME FORMAT TMSF 

TIME FORMAT TMSF 

Sets the time format to tt.mm.ss.ff where ff is tracks, mm is minutes, ss is seconds, and /f is frames. All position information is in 
this format after this command. The ff input can be omitted if it is 0, can be omitted if both 55 and ff are 0, and mm can be 
omitted if mm , ss, and ff all equal 0. These fields have the following maximum values: 

Tracks (ff) 

99 


Minutes (mm) 

99 


Seconds (ss) 

59 


Frames (ff) 

74 



SET (CD Audio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 



SET (CD Audio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SET (CD Audio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

AUDIO 

Sets the audio attributes of the device context specified by the ALL, LEFT, RIGHT, OVER, and VOLUME keywords. 

ALL 

Applies to both/all channels (default). 

Specify ON or OFF with the ALL keyword. 

ON 

Enables audio output. 

OFF 

Disables audio output. 

LEFT 

Applies to left channel. 

Specify ON or OFF with the LEFT keyword. 

ON 

Enables audio output to the left channel. 

OFF 

Disables audio output to the left channel. 


RIGHT 


Applies to right channel. 

Specify ON or OFF with the RIGHT keyword. 

ON 

Enables audio output to the right channel. 


OFF 


Disables audio output to the right channel. 


OVER milliseconds 

Applies the change over the specified time period (fade). 

VOLUME percentage 

Sets the device/mixer channel volume level. 


DOOR CLOSED 


Retracts the tray and closes the door, if possible. 


DOOR LOCKED 

Locks the media cover on the device (if any). This disables manual ejection of the media from the device. 

DOOR OPEN 

Opens the door and ejects the tray, if possible. This enables manual ejection of the media from the device. 

DOOR UNLOCKED 

Unlocks the media cover on the device (if any). This enables manual ejection of the media from the device. 

TIME FORMAT MILLISECONDS 

Sets the time format to milliseconds. All position information is in this format after this command. You can abbreviate as ms. 

TIME FORMAT MMTIME 

Sets the time format to MMTIME. 

TIME FORMAT MSF 

Sets the time format to mm:ss:ff , where mm is minutes, ss is seconds, and ff is frames. All position information is in this format 
after this command. The ff input can be omitted if it is 0; ss can be omitted if both ss and ff are 0. These fields have the following 
maximum values: 

Minutes {mm) 99 

Seconds (ss) 59 

Frames (ff) 74 

TIME FORMAT TMSF 

Sets the time format to tt:mm:ss:ff where ft is tracks, mm is minutes, ss is seconds, and ff is frames. All position information is in 
this format after this command. The ff input can be omitted if it is 0, ss can be omitted if both ss and ff are 0, and mm can be 
omitted if mm, ss, and ff all equal 0. These fields have the following maximum values: 

Tracks (//) 99 

Minutes (mm) 99 

Seconds (ss) 59 

Frames (ff) 74 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


SET (CD Audio Command) - Syntax Diagram 


SET 


object 


AUDIO 


ALL 


ON 

OFF 

ON 

OFF 

ON 


LEFT 


RIGHT ON 

OFF 


OVER milliseconds 
VOLUME percentage 


DOOR CLOSED 
DOOR LOCKED 
DOOR OPEN 
DOOR UNLOCKED 


TIME FORMAT MILLISECONDS 
TIME FORMAT MMTIME 
TIME FORMAT MSF 
TIME FORMAT TMSF 


WAIT 

NOTIFY 


Examples 
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STATUS 


STATUS (CD Audio Command) - Example 


status cdaudio mode wait 


STATUS (CD Audio Command) - Purpose 


The STATUS command obtains status information for the device. 


STATUS (CD Audio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 


Device type 



Device name 

Filename 

Alias 


STATUS (CD Audio Command) Keyword - CHANNELS 


CHANNELS 

Returns the number of audio channels on the current track. 


STATUS (CD Audio Command) Keyword - CHANNELS 
TRACK number 


CHANNELS TRACK number 

Returns the number of audio channels on the track. 


STATUS (CD Audio Command) Keyword - 
COPYPERMITTED 


COPYPERMITTED 

Returns TRUE if digital copying is permitted. 


STATUS (CD Audio Command) Keyword - 
COPYPERMITTED TRACK number 


COPYPERMITTED TRACK number 

Returns TRUE if digital copying is permitted. 


STATUS (CD Audio Command) Keyword - CURRENT 
TRACK 


CURRENT TRACK 

Returns the current track. 



STATUS (CD Audio Command) Keyword - LENGTH 


LENGTH 

Returns the total length of the disc. 


STATUS (CD Audio Command) Keyword - LENGTH TRACK 
number 


LENGTH TRACK number 

Returns the length of the track specified by number. 


STATUS (CD Audio Command) Keyword - MEDIA PRESENT 


MEDIA PRESENT 

Returns TRUE if the media is inserted in the device; otherwise, it returns FALSE. 


STATUS (CD Audio Command) Keyword - MODE 


MODE 

Returns the current mode of the device: not ready, stopped, playing, seeking, recording, paused, or other. 


STATUS (CD Audio Command) Keyword - NUMBER OF 
TRACKS 


NUMBER OF TRACKS 

Returns the number of tracks. 


STATUS (CD Audio Command) Keyword - POSITION 



POSITION 

Returns the current position. 


STATUS (CD Audio Command) Keyword - POSITION IN 
TRACK 


POSITION IN TRACK 

Returns the current position relative to the beginning of the current track. 


STATUS (CD Audio Command) Keyword - POSITION TRACK 
number 

POSITION TRACK number 

Returns the starting position of the track specified by number. 


STATUS (CD Audio Command) Keyword - PREEMPHASIS 


PREEMPHASIS 

Returns TRUE if the current track was recorded with pre-emphasis. 


STATUS (CD Audio Command) Keyword - PREEMPHASIS 
TRACK number 

PREEMPHASIS TRACK number 

Returns TRUE if the specified track was recorded with pre-emphasis. 


STATUS (CD Audio Command) Keyword - READY 


READY 

Returns TRUE if the device is ready. 



STATUS (CD Audio Command) Keyword - START POSITION 


START POSITION 

Returns the starting position of the media. 


STATUS (CD Audio Command) Keyword - TIME FORMAT 


TIME FORMAT 

Returns the time format. 


STATUS (CD Audio Command) Keyword - TYPE 


TYPE 

Returns the track type of the current track. The track type will be returned as one of the following values: 

• audio 

• data 

• other 


STATUS (CD Audio Command) Keyword - TYPE TRACK 
number 

TYPE TRACK number 

Returns the track type of the specified track. If the track number is not specified the current track is assumed. The track type will be 
returned as one of the following values: 

• audio 

• data 

• other 


STATUS (CD Audio Command) Keyword - VOLUME 


VOLUME 

Returns the current volume setting. The volume is returned as a string in the format /eft.right where /eft and right are percentages of 



the maximum achievable effect for the left and right channels respectively. Leading zeros are suppressed for the volume level in each 
channel. 


STATUS (CD Audio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


STATUS (CD Audio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (CD Audio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


Note: If TRACK number is used with the keywords TYPE, COPYPERMITTED, CPIANNELS, or PREEMPHASIS, then the specified track is 
referenced, otherwise, the current track is referenced. 


CHANNELS 

Returns the number of audio channels on the current track. 

CHANNELS TRACK number 

Returns the number of audio channels on the track. 

COPYPERMITTED 

Returns TRUE if digital copying is permitted. 

COPYPERMITTED TRACK number 

Returns TRUE if digital copying is permitted. 

CURRENT TRACK 

Returns the current track. 

LENGTH 

Returns the total length of the disc. 

LENGTH TRACK number 

Returns the length of the track specified by number. 


MEDIA PRESENT 

Returns TRUE if the media is inserted in the device; otherwise, it returns FALSE. 

MODE 

Returns the current mode of the device: not ready, stopped, playing, seeking, recording, paused, or other. 

NUMBER OF TRACKS 

Returns the number of tracks. 

POSITION 

Returns the current position. 

POSITION IN TRACK 

Returns the current position relative to the beginning of the current track. 

POSITION TRACK number 

Returns the starting position of the track specified by number. 

PREEMPHASIS 

Returns TRUE if the current track was recorded with pre-emphasis. 

PREEMPHASIS TRACK number 

Returns TRUE if the specified track was recorded with pre-emphasis. 

READY 

Returns TRUE if the device is ready. 

START POSITION 

Returns the starting position of the media. 

TIME FORMAT 

Returns the time format. 


TYPE 

Returns the track type of the current track. The track type will be returned as one of the following values: 

• audio 

• data 

• other 

TYPE TRACK number 

Returns the track type of the specified track. If the track number is not specified the current track is assumed. The track type will be 
returned as one of the following values: 

• audio 

• data 

• other 

VOLUME 

Returns the current volume setting. The volume is returned as a string in the format teftright where /eft and right are percentages of 
the maximum achievable effect for the left and right channels respectively. Leading zeros are suppressed for the volume level in each 
channel. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (CD Audio Command) - Syntax Diagram 


STATUS 


object 


CHANNELS 


CHANNELS TRACK number WAIT 

COPYPERMITTED NOTIFY 

COPYPERMITTED TRACK number 
CURRENT TRACK 
LENGTH 

LENGTH TRACK number 
MEDIA PRESENT 
MODE 

NUMBER OF TRACKS 
POSITION 

POSITION IN TRACK 
POSITION TRACK number 
PREEMPHASIS 

PREEMPHASIS TRACK number 
READY 

START POSITION 
TIME FORMAT 
TYPE 

TYPE TRACK number 
VOLUME 


Examples 
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CD/XA Commands 


The CD/XA audio device supports the device-type specific command, CUE, and extensions to the following basic and required commands: 

• CAPABILITY 

• CONNECTOR 

• CUE 
INFO 

• PLAY 
SEEK 

• SET 
STATUS 


CAPABILITY 


CAPABILITY (CD/XA Command) - Example 



capability cdxa can record wait 


CAPABILITY (CD/XA Command) - Purpose 


The CAPABILITY command requests additional information about the capabilities of the CD/XA device. 


CAPABILITY (CD/XA Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CAPABILITY (CD/XA Command) Keyword - CAN EJECT 


CAN EJECT 

Returns TRUE if the CD/XA device can eject the media. 


CAPABILITY (CD/XA Command) Keyword - CAN 
LOCKEJECT 


CAN LOCKEJECT 

Returns TRUE if the device can disable manual ejection of the media. 


CAPABILITY (CD/XA Command) Keyword - CAN PLAY 


CAN PLAY 

Returns TRUE if the CD/XA device can play the media. 



CAPABILITY (CD/XA Command) Keyword - CAN PROCESS 
INTERNAL 


CAN PROCESS INTERNAL 

Returns TRUE if the device can internally process digital data with an internal digital to analog converter (DAC). 


CAPABILITY (CD/XA Command) Keyword - CAN RECORD 


CAN RECORD 

Returns FALSE. CD/XA devices cannot record. 


CAPABILITY (CD/XA Command) Keyword - CAN SAVE 


CAN SAVE 

Returns FALSE. CD/XA devices cannot save data. 


CAPABILITY (CD/XA Command) Keyword - CAN 
SETVOLUME 


CAN SETVOLUME 

Returns TRUE if the device supports software control of volume level. 


CAPABILITY (CD/XA Command) Keyword - CAN STREAM 


CAN STREAM 

Returns TRUE if the device can continuously transfer digital data to or from another device. The source or destination of the data is 
determined by the device context connection. 


CAPABILITY (CD/XA Command) Keyword - COMPOUND 



DEVICE 


COMPOUND DEVICE 

Returns TRUE. CD/XA devices are compound devices and utilize files. 


CAPABILITY (CD/XA Command) Keyword - DEVICE TYPE 


DEVICE TYPE 

Returns CDXA. 


CAPABILITY (CD/XA Command) Keyword - HAS AUDIO 


HAS AUDIO 

Returns TRUE. 


CAPABILITY (CD/XA Command) Keyword - HAS VIDEO 


HAS VIDEO 

Returns FALSE if no video available. CD/XA devices do not support video for this release of the Toolkit. 


CAPABILITY (CD/XA Command) Keyword - PREROLL TIME 


PREROLL TIME 

Returns 0, indicating the preroll time is not bounded. 


CAPABILITY (CD/XA Command) Keyword - PREROLL TYPE 


PREROLL TYPE 

Returns the preroll characteristics of the device: Returns NONE. 



CAPABILITY (CD/XA Command) Keyword - USES FILES 


USES FILES 

Returns TRUE. 


CAPABILITY (CD/XA Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


CAPABILITY (CD/XA Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPABILITY (CD/XA Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 

CAN EJECT 

Returns TRUE if the CD/XA device can eject the media. 

CAN LOCKEJECT 

Returns TRUE if the device can disable manual ejection of the media. 

CAN PLAY 

Returns TRUE if the CD/XA device can play the media. 

CAN PROCESS INTERNAL 

Returns TRUE if the device can internally process digital data with an internal digital to analog converter (DAC). 

CAN RECORD 

Returns FALSE. CD/XA devices cannot record. 

CAN SAVE 

Returns FALSE. CD/XA devices cannot save data. 

CAN SETVOLUME 

Returns TRUE if the device supports software control of volume level. 


CAN STREAM 

Returns TRUE if the device can continuously transfer digital data to or from another device. The source or destination of the data is 
determined by the device context connection. 

COMPOUND DEVICE 

Returns TRUE. CD/XA devices are compound devices and utilize files. 

DEVICE TYPE 

Returns CDXA. 

HAS AUDIO 

Returns TRUE. 

HAS VIDEO 

Returns FALSE if no video available. CD/XA devices do not support video for this release of the Toolkit. 

PREROLL TIME 

Returns 0, indicating the preroll time is not bounded. 

PREROLL TYPE 

Returns the preroll characteristics of the device: Returns NONE. 

USES FILES 

Returns TRUE. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPABILITY (CD/XA Command) - Syntax Diagram 


CAPABILITY object 


CAN EJECT 
CAN LOCKE JECT 
CAN PLAY 

CAN PROCESS INTERNAL 
CAN RECORD 
CAN SAVE 
CAN STREAM 
CAN SETVOLUME 
COMPOUND DEVICE 
DEVICE TYPE 
HAS AUDIO 
HAS VIDEO 
PREROLL TIME 
PREROLL TYPE 
USES FILES 


WAIT 

NOTIFY 


Examples 


CAPABILITY (CD/XA Command) - Topics 


Select an item: 



Purpose 
Syntax Diagram 
Keywords 
Example 
Glossary 


CONNECTOR 


CONNECTOR (CD/XA Command) - Example 


connector cdxa query type XA stream wait 


CONNECTOR (CD/XA Command) - Purpose 


The CONNECTOR command enables, disables, or queries the status of connectors on a device. 


CONNECTOR (CD/XA Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CONNECTOR (CD/XA Command) Keyword - ENABLE 


ENABLE 

Enables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 


CONNECTOR (CD/XA Command) Keyword - DISABLE 


DISABLE 

Disables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 


CONNECTOR (CD/XA Command) Keyword - QUERY 


QUERY 

Queries the status of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled. Use of 
this option requires that the NUMBER or TYPE keywords, or both also be specified. 


CONNECTOR (CD/XA Command) Keyword - NUMBER 
connector number 


NUMBER connectornumber 

Indicates the connector number on which to perform the requested action. If this item is omitted, then the first connector is assumed. 
If the TYPE keyword is included, the connector number is interpreted as a relative offset within the specified connector type. 


CONNECTOR (CD/XA Command) Keyword - TYPE 
connector_type 


TYPE connector type 

Indicates the type of connector to which the requested action applies. The following connector types are supported by this device. 


XA stream 


Digital output for the audio amplifier/mixer. This connector is always enabled. 


CONNECTOR (CD/XA Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


CONNECTOR (CD/XA Command) Keyword - NOTIFY 



NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTOR (CD/XA Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

ENABLE 

Enables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 

DISABLE 

Disables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 

QUERY 

Queries the status of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled. Use of 
this option requires that the NUMBER or TYPE keywords, or both also be specified. 

NUMBER connector number 

Indicates the connector number on which to perform the requested action. If this item is omitted, then the first connector is assumed. 
If the TYPE keyword is included, the connector number is interpreted as a relative offset within the specified connector type. 

TYPE connector type 

Indicates the type of connector to which the requested action applies. The following connector types are supported by this device. 
XA stream 

Digital output for the audio amplifier/mixer. This connector is always enabled. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


CONNECTOR (CD/XA Command) - Syntax Diagram 


CONNECTOR object 


ENABLE 

DISABLE 

QUERY 


NUMBER connector_number 
TYPE connector_type 


WAIT 

NOTIFY 


Examples 
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CUE 


CUE (CD/XA Command) - Example 


open cdxa alias cd shareable wait 
load cd \brazil\carnival . xa wait 
cue cd output wait 


CUE (CD/XA Command) - Purpose 


The CUE command prepares for playback. The CUE command does not have to be issued prior to playback; however, depending on the 
device, it might reduce the delay associated with the CUE command. 

The CUE command is not related to the SETCUEPOINT command. 


CUE (CD/XA Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 


Device type 
Device name 
Filename 



Alias 


CUE (CD/XA Command) Keyword - OUTPUT 


OUTPUT 

Cues the device for playback. 


CUE (CD/XA Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CUE (CD/XA Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CUE (CD/XA Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

OUTPUT 

Cues the device for playback. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CUE (CD/XA Command) - Syntax Diagram 


CUE 


object 


OUTPUT 


WAIT 

NOTIFY 


Examples 


CUE (CD/XA Command) - Topics 
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INFO 


INFO (CD/XA Command) - Example 


info cdxa product wait 


INFO (CD/XA Command) - Purpose 


The INFO command fills a user-supplied buffer with information. 


INFO (CD/XA Command) Keyword - object 


object 


Object associated with this media control interface command. The object can be one of the following 



Device type 
Device name 
Filename 
Alias 


INFO (CD/XA Command) Keyword - ID 


ID 

Returns the disc ID if the device supports this function, otherwise, it returns 0. The value returned is a binary value. 


INFO (CD/XA Command) Keyword - PRODUCT 


PRODUCT 

Returns the product name and model of the current audio device. 


INFO (CD/XA Command) Keyword - UPC 


UPC 

Returns the disc UPC code (serial number) if the device supports this function, otherwise, it returns 0. The value returned is a binary 
value. 


INFO (CD/XA Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


INFO (CD/XA Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


INFO (CD/XA Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

ID 

Returns the disc ID if the device supports this function, otherwise, it returns 0. The value returned is a binary value. 

PRODUCT 

Returns the product name and model of the current audio device. 

UPC 

Returns the disc UPC code (serial number) if the device supports this function, otherwise, it returns 0. The value returned is a binary 
value. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


INFO (CD/XA Command) - Syntax Diagram 


INFO object 


ID 

PRODUCT 

UPC 


WAIT 

NOTIFY 


Examples 
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PLAY 



PLAY (CD/XA Command) - Example 


play cdxa from 10000 to 50000 wait 


PLAY (CD/XA Command) - Purpose 


The PLAY command starts playing audio. 


PLAY (CD/XA Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


PLAY (CD/XA Command) Keyword - FROM pos 


FROM pos 

The position to start playing. If FROM is omitted, the device starts playing at the current position. If the FROM position is greater than 
the end position of the disc, or if the FROM position is greater than the TO position, an error is returned. 


PLAY (CD/XA Command) Keyword - TO pos 


TO pos 

The position to stop playing. If TO is omitted, play stops at the end of the disc. If the TO position is greater than the length of the disc, 
it receives an MCIERR_OUTOFRANGE error. 


PLAY (CD/XA Command) Keyword - WAIT 



WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


PLAY (CD/XA Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


PLAY (CD/XA Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

FROM pos 

The position to start playing. If FROM is omitted, the device starts playing at the current position. If the FROM position is greater than 
the end position of the disc, or if the FROM position is greater than the TO position, an error is returned. 

TO pos 

The position to stop playing. If TO is omitted, play stops at the end of the disc. If the TO position is greater than the length of the disc, 
it receives an MCIERR_OUTOFRANGE error. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


PLAY (CD/XA Command) - Syntax Diagram 


PLAY 


object 


FROM pos 
TO pos 


WAIT 

NOTIFY 


Examples 
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SEEK 


SEEK (CD/XA Command) - Example 


open cdxa alias cd shareable wait 
load cd music. xa wait 
seek cd to end wait 


SEEK (CD/XA Command) - Purpose 


The SEEK command finds the specified location on the disc. 

Note: Seeking to a given position in a CD-XA file requires the media control driver to essentially play to that point from the beginning of the 
file. 


SEEK (CD/XA Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 



SEEK (CD/XA Command) Keyword - TO pos 


TO pos 

The destination position for the seek. If it is greater than the length of the disc, an MCIERR_OUTOFRANGE error is returned. 


SEEK (CD/XA Command) Keyword - TO START 


TO START 

Seeks to the first playable location on the disc. 


SEEK (CD/XA Command) Keyword - TO END 


TO END 

Seeks to the end of the disc. 


SEEK (CD/XA Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SEEK (CD/XA Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SEEK (CD/XA Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


TO pos 

The destination position for the seek. If it is greater than the length of the disc, an MCIERR_OUTOFRANGE error is returned. 

TO START 

Seeks to the first playable location on the disc. 

TO END 

Seeks to the end of the disc. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SEEK (CD/XA Command) - Syntax Diagram 


SEEK 

object 

TO pos 
TO START 

WAIT 



TO END 

NOTIFY 


Examples 
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SET 



SET (CD/XA Command) - Example 


set cdxa door open wait 


SET (CD/XA Command) - Purpose 


The SET command sets the various control items. 


SET (CD/XA Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


SET (CD/XA Command) Keyword - AUDIO 


AUDIO 

Sets the audio attributes of the device context specified by the ALL, LEFT, RIGFIT, OVER, and VOLUME keywords. 


SET (CD/XA Command) Keyword - ALL 


ALL 

Applies to both/all channels (default). 
Specify ON or OFF with the ALL keyword. 


SET (CD/XA Command) Keyword - ON 


ON 



Enables audio output. 


SET (CD/XA Command) Keyword - OFF 


OFF 

Disables audio output. 


SET (CD/XA Command) Keyword - LEFT 


LEFT 

Applies to left channel. 

Specify ON or OFF with the LEFT keyword. 


SET (CD/XA Command) Keyword - ON 


ON 

Enables audio output to the left channel. 


SET (CD/XA Command) Keyword - OFF 


OFF 

Disables audio output to the left channel. 


SET (CD/XA Command) Keyword - RIGHT 


RIGHT 

Applies to right channel. 

Specify ON or OFF with the RIGFIT keyword. 


SET (CD/XA Command) Keyword - ON 



ON 


Enables audio output to the right channel. 


SET (CD/XA Command) Keyword - OFF 


OFF 

Disables audio output to the right channel. 


SET (CD/XA Command) Keyword - OVER milliseconds 


OVER milliseconds 

Applies the change over the specified time period (fade). 


SET (CD/XA Command) Keyword - VOLUME percentage 


VOLUME percentage 

Sets the device/mixer channel volume level. 


SET (CD/XA Command) Keyword - CHANNEL number 


CHANNEL number 

Channel number to set for the given device. 


SET (CD/XA Command) Keyword - AUDIO DEVICE 


AUDIO DEVICE 

Channel set pertains to the audio device. 


SET (CD/XA Command) Keyword - DOOR CLOSED 



DOOR CLOSED 

Retracts the tray and closes the door, if possible. 


SET (CD/XA Command) Keyword - DOOR LOCKED 


DOOR LOCKED 

Locks the media cover on the device (if any). This disables manual ejection of the media from the device. 


SET (CD/XA Command) Keyword - DOOR OPEN 


DOOR OPEN 

Opens the door and ejects the tray, if possible. This enables manual ejection of the media from the device. 


SET (CD/XA Command) Keyword - DOOR UNLOCKED 


DOOR UNLOCKED 

Unlocks the media cover on the device (if any). This enables manual ejection of the media from the device. 


SET (CD/XA Command) Keyword - TIME FORMAT 
MILLISECONDS 


TIME FORMAT MILLISECONDS 

Sets time format, to milliseconds. All position information is in this format after this command. You can abbreviate milliseconds as ms. 


SET (CD/XA Command) Keyword - TIME FORMAT MMTIME 


TIME FORMAT MMTIME 

The time format is set to MMTIME. 



SET (CD/XA Command) Keyword - TIME FORMAT MSF 


TIME FORMAT MSF 

Sets the time format to mm:ss:ff , where mm is minutes, ss is seconds, and ff is frames. All position information is in this format 
after this command. 


SET (CD/XA Command) Keyword - TIME FORMAT TMSF 


TIME FORMAT TMSF 

Sets the time format to tt:mm:ss:ff where tt is tracks, mm is minutes, ss is seconds, and ff is frames. All position information is in 
this format after this command. 


SET (CD/XA Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SET (CD/XA Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SET (CD/XA Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

AUDIO 

Sets the audio attributes of the device context specified by the ALL, LEFT, RIGHT, OVER, and VOLUME keywords. 

ALL 

Applies to both/all channels (default). 


Specify ON or OFF with the ALL keyword. 


LEFT 


RIGHT 


ON 


OFF 


Enables audio output. 


Disables audio output. 


Applies to left channel. 

Specify ON or OFF with the LEFT keyword. 

ON 


OFF 


Enables audio output to the left channel. 


Disables audio output to the left channel. 


Applies to right channel. 

Specify ON or OFF with the FtIGFIT keyword. 

ON 


OFF 


Enables audio output to the right channel. 


Disables audio output to the right channel. 


OVER milliseconds 

Applies the change over the specified time period (fade). 

VOLUME percentage 

Sets the device/mixer channel volume level. 


CHANNEL number 

Channel number to set for the given device. 

AUDIO DEVICE 

Channel set pertains to the audio device. 

DOOR CLOSED 

Retracts the tray and closes the door, if possible. 

DOOR LOCKED 

Locks the media cover on the device (if any). This disables manual ejection of the media from the device. 

DOOR OPEN 

Opens the door and ejects the tray, if possible. This enables manual ejection of the media from the device. 

DOOR UNLOCKED 

Unlocks the media cover on the device (if any). This enables manual ejection of the media from the device. 

TIME FORMAT MILLISECONDS 

Sets time format, to milliseconds. All position information is in this format after this command. You can abbreviate milliseconds as ms. 

TIME FORMAT MMTIME 

The time format is set to MMTIME. 

TIME FORMAT MSF 

Sets the time format to mm:ss:ft , where mm is minutes, ss is seconds, and ff is frames. All position information is in this format 
after this command. 

TIME FORMAT TMSF 

Sets the time format to tt:mm:ss:ff where tt is tracks, mm is minutes, ss is seconds, and ff is frames. All position information is in 
this format after this command. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 



NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SET (CD/XA Command) - Syntax Diagram 


SET object AUDIO 


ALL 

ON 


OFF 

LEFT 

ON 


OFF 

RIGHT 

ON 


OFF 


OVER milliseconds 
VOLUME percentage 
CHANNEL number 

AUDIO DEVICE 

DOOR CLOSED 

DOOR LOCKED 

DOOR OPEN 

DOOR UNLOCKED 

TIME FORMAT MILLISECONDS 

TIME FORMAT MMTIME 

TIME FORMAT MSF 

TIME FORMAT TMSF 


WAIT 

NOTIFY 


Examples 
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STATUS 


STATUS (CD/XA Command) - Example 



status cdxa mode wait 


STATUS (CD/XA Command) - Purpose 

The STATUS command obtains status information for the device. 


STATUS (CD/XA Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


STATUS (CD/XA Command) Keyword - CHANNEL number 


CHANNEL number 

Returns audio device, audio buffer, video buffer, data buffer, none, right, all, or left for the destination of the data in the channel 
specified by number. 


STATUS (CD/XA Command) Keyword - LENGTH 


LENGTH 

Returns MCIERR_INDETERMINATE_LENGTH. The length of a CD-XA file cannot be determined in this release of OS/2 multimedia. 


STATUS (CD/XA Command) Keyword - MEDIA PRESENT 


MEDIA PRESENT 

Returns TRUE if the media is inserted in the device; otherwise, it returns FALSE. 



STATUS (CD/XA Command) Keyword - MODE 


MODE 

Returns the current mode of the device: not ready, stopped, playing, seeking, recording, paused, or other. 


STATUS (CD/XA Command) Keyword - POSITION 


POSITION 

Returns the current position. 


STATUS (CD/XA Command) Keyword - READY 


READY 

Returns TRUE if the device is ready. 


STATUS (CD/XA Command) Keyword - TIME FORMAT 


TIME FORMAT 

Returns the time format. 


STATUS (CD/XA Command) Keyword - VOLUME 


VOLUME 

Returns the current volume setting. The volume is returned as a string in the format /eftright where /eft and right are percentages of 
the maximum achievable effect for the left and right channels respectively. Leading zeros are suppressed for the volume level in each 
channel. 


STATUS (CD/XA Command) Keyword - WAIT 


WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 



application. The WAIT keyword must be specified in order to receive return string information. 


STATUS (CD/XA Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (CD/XA Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 

CFIANNEL number 

Returns audio device, audio buffer, video buffer, data buffer, none, right, all, or left for the destination of the data in the channel 
specified by number. 

LENGTH 

Returns MCIERR_INDETERMINATE_LENGTFI. The length of a CD-XA file cannot be determined in this release of OS/2 multimedia. 

MEDIA PRESENT 

Returns TRUE if the media is inserted in the device; otherwise, it returns FALSE. 

MODE 

Returns the current mode of the device: not ready, stopped, playing, seeking, recording, paused, or other. 

POSITION 

Returns the current position. 

READY 

Returns TRUE if the device is ready. 

TIME FORMAT 

Returns the time format. 

VOLUME 

Returns the current volume setting. The volume is returned as a string in the format ieftr/ght where /eft and right are percentages of 
the maximum achievable effect for the left and right channels respectively. Leading zeros are suppressed for the volume level in each 
channel. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (CD/XA Command) - Syntax Diagram 


STATUS object CHANNEL number 

LENGTH WAIT 

MEDIA PRESENT NOTIFY 

MODE 

POSITION 

READY 

TIME FORMAT 
VOLUME 
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Digital Video Commands 


The digital video device supports the following device-type specific commands and extensions to the following basic and required 
commands: 


CAPABILITY 

• CONNECTOR 

• COPY 

• CUE 

• CUT 

• DELETE 
INFO 

• LOAD 
OPEN 

• PASTE 
PLAY 

• PUT 
RECORD 

• REDO 
SAVE 

• REWIND 

• SEEK 

• SET 
SETTUNER 

• STATUS 
STEP 

• UNDO 

• WHERE 

• WINDOW 



CAPABILITY 


CAPABILITY (Digital Video Command) - Example 


capability digitalvideo can distort wait 


CAPABILITY (Digital Video Command) - Purpose 


The CAPABILITY command requests information about the capabilities of the device driver. 


CAPABILITY (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CAPABILITY (Digital Video Command) Keyword - CAN 
DISTORT 


CAN DISTORT 

Returns FALSE for most frame-grabber types of hardware. Flowever, some hardware, such as Video Blaster, is capable of 
performing independent scaling in the horizontal and vertical directions and return TRUE. 


CAPABILITY (Digital Video Command) Keyword - CAN 
EJECT 


CAN EJECT 



Returns FALSE. The digital video device cannot eject media. 


CAPABILITY (Digital Video Command) Keyword - CAN 
LOCKEJECT 


CAN LOCKEJECT 

Returns TRUE if the device can disable manual ejection of the media. 


CAPABILITY (Digital Video Command) Keyword - CAN PLAY 


CAN PLAY 

Returns TRUE if the device can play. 


CAPABILITY (Digital Video Command) Keyword - CAN 
PROCESS INTERNAL 


CAN PROCESS INTERNAL 

Returns TRUE if the device can internally process digital data with an internal digital to analog converter (DAC). 


CAPABILITY (Digital Video Command) Keyword - CAN 
RECORD 


CAN RECORD 

Returns TRUE if the digital video device can record. 


CAPABILITY (Digital Video Command) Keyword - CAN 
RECORD INSERT 


CAN RECORD INSERT 

Returns TRUE if the digital video device can insert data in the file. It expands the file and does not overwrite the information that is 
present. 



CAPABILITY (Digital Video Command) Keyword - CAN 
REVERSE 


CAN REVERSE 

Returns FALSE. The digital video device can not play in reverse. 


CAPABILITY (Digital Video Command) Keyword - CAN 
SETVOLUME 


CAN SETVOLUME 

Returns TRUE if the device supports software control of volume level. 


CAPABILITY (Digital Video Command) Keyword - CAN 
STREAM 


CAN STREAM 

Returns TRUE if the device can continuously transfer digital data to and from another device. The source or destination of the data is 
determined by the device context connection. 


CAPABILITY (Digital Video Command) Keyword - CAN 
STRETCH 


CAN STRETCH 

Returns FALSE for most frame-grabber types hardware. Flowever, some hardware, such as Video Blaster, is capable of performing 
scaling and returns TRUE. 


CAPABILITY (Digital Video Command) Keyword - 
COMPOUND DEVICE 


COMPOUND DEVICE 

Returns TRUE if the device requires an element name. 



CAPABILITY (Digital Video Command) Keyword - DEVICE 
TYPE 


DEVICE TYPE 

Returns Digitalvideo. 


CAPABILITY (Digital Video Command) Keyword - FAST 
PLAY RATE 


FAST PLAY RATE 

Returns twice the normal recorded playback rate. Returns 0 if the device cannot play fast. 


CAPABILITY (Digital Video Command) Keyword - HAS 
AUDIO 


HAS AUDIO 

Returns TRUE if the device has audio playback. 


CAPABILITY (Digital Video Command) Keyword - HAS 
IMAGE 


HAS IMAGE 

Returns FALSE. The digital video device does not support still image functions. 


CAPABILITY (Digital Video Command) Keyword - HAS 
TUNER 


HAS TUNER 

Returns TRUE if the device has TV tuner capabilities. 



CAPABILITY (Digital Video Command) Keyword - HAS 
VIDEO 


HAS VIDEO 

Returns TRUE. 


CAPABILITY (Digital Video Command) Keyword - 
HORIZONTAL IMAGE EXTENT 


HORIZONTAL IMAGE EXTENT 

Returns the horizontal (X) source extent for images. 


CAPABILITY (Digital Video Command) Keyword - 
HORIZONTAL VIDEO EXTENT 


HORIZONTAL VIDEO EXTENT 

Returns the horizontal (X) source extent for the video source. 


CAPABILITY (Digital Video Command) Keyword - MAXIMUM 
PLAY RATE 


MAXIMUM PLAY RATE 

Not supported. 


CAPABILITY (Digital Video Command) Keyword - MESSAGE 
command 


MESSAGE command 

Returns TRUE if the device supports the command specified by command. The command can be any string command such as 



OPEN, PLAY, and so on. 


CAPABILITY (Digital Video Command) Keyword - MINIMUM 
PLAY RATE 


MINIMUM PLAY RATE 

Not supported. 


CAPABILITY (Digital Video Command) Keyword - NORMAL 
PLAY RATE 


NORMAL PLAY RATE 

Returns the normal recorded playback rate of the currently loaded motion video device element, in the current speed format, either as 
a percentage or in frames per second. Otherwise, returns 0. 


CAPABILITY (Digital Video Command) Keyword - OVERLAY 
GRAPHICS 


OVERLAY GRAPHICS 

Returns FALSE. Overlay cards such as Video Blaster enable graphics overlay of the hardware monitor window, however, overlay is 
not supported over digital video playback in the graphics buffer. 


CAPABILITY (Digital Video Command) Keyword - PREROLL 
TIME 


PREROLL TIME 

Returns 0, indicating the preroll time is not bounded. 


CAPABILITY (Digital Video Command) Keyword - PREROLL 
TYPE 



PREROLL TYPE 

Returns the preroll characteristics of the device. Returns NOTIFIED. 


CAPABILITY (Digital Video Command) Keyword - SLOW 
PLAY RATE 


SLOW PLAY RATE 

Returns half the normal recorded playback rate. Returns 0 if the device cannot play slow. 


CAPABILITY (Digital Video Command) Keyword - USES 
FILES 


USES FILES 

Returns TRUE if the element of a compound device is a file path name. 


CAPABILITY (Digital Video Command) Keyword - VERTICAL 
IMAGE EXTENT 


VERTICAL IMAGE EXTENT 

Returns the vertical (Y) source extent for images. 


CAPABILITY (Digital Video Command) Keyword - VERTICAL 
VIDEO EXTENT 


VERTICAL VIDEO EXTENT 

Returns the vertical (Y) source extent for the video source. 


CAPABILITY (Digital Video Command) Keyword - WINDOWS 


WINDOWS 

Not supported. 



CAPABILITY (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


CAPABILITY (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returns immediately to the application. When the requested action 
is complete an MM_MCINOTIFY message is sent to the application window procedure. 


CAPABILITY (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

CAN DISTORT 

Returns FALSE for most frame-grabber types of hardware. Flowever, some hardware, such as Video Blaster, is capable of 
performing independent scaling in the horizontal and vertical directions and return TRUE. 

CAN EJECT 

Returns FALSE. The digital video device cannot eject media. 

CAN LOCKEJECT 

Returns TRUE if the device can disable manual ejection of the media. 

CAN PLAY 

Returns TRUE if the device can play. 

CAN PROCESS INTERNAL 

Returns TRUE if the device can internally process digital data with an internal digital to analog converter (DAC). 

CAN RECORD 

Returns TRUE if the digital video device can record. 

CAN RECORD INSERT 

Returns TRUE if the digital video device can insert data in the file. It expands the file and does not overwrite the information that is 
present. 

CAN REVERSE 

Returns FALSE. The digital video device can not play in reverse. 

CAN SETVOLUME 

Returns TRUE if the device supports software control of volume level. 


CAN STREAM 


Returns TRUE if the device can continuously transfer digital data to and from another device. The source or destination of the data is 
determined by the device context connection. 

CAN STRETCH 

Returns FALSE for most frame-grabber types hardware. Flowever, some hardware, such as Video Blaster, is capable of performing 
scaling and returns TRUE. 

COMPOUND DEVICE 

Returns TRUE if the device requires an element name. 

DEVICE TYPE 

Returns Digitalvideo. 

FAST PLAY RATE 

Returns twice the normal recorded playback rate. Returns 0 if the device cannot play fast. 

HAS AUDIO 

Returns TRUE if the device has audio playback. 

HAS IMAGE 

Returns FALSE. The digital video device does not support still image functions. 

HAS TUNER 

Returns TRUE if the device has TV tuner capabilities. 

HAS VIDEO 

Returns TRUE. 

HORIZONTAL IMAGE EXTENT 

Returns the horizontal (X) source extent for images. 

HORIZONTAL VIDEO EXTENT 

Returns the horizontal (X) source extent for the video source. 

MAXIMUM PLAY RATE 

Not supported. 

MESSAGE command 

Returns TRUE if the device supports the command specified by command. The command can be any string command such as 
OPEN, PLAY, and so on. 

MINIMUM PLAY RATE 

Not supported. 

NORMAL PLAY RATE 

Returns the normal recorded playback rate of the currently loaded motion video device element, in the current speed format, either as 
a percentage or in frames per second. Otherwise, returns 0. 

OVERLAY GRAPHICS 

Returns FALSE. Overlay cards such as Video Blaster enable graphics overlay of the hardware monitor window, however, overlay is 
not supported over digital video playback in the graphics buffer. 

PREROLL TIME 

Returns 0, indicating the preroll time is not bounded. 

PREROLL TYPE 

Returns the preroll characteristics of the device. Returns NOTIFIED. 

SLOW PLAY RATE 

Returns half the normal recorded playback rate. Returns 0 if the device cannot play slow. 

USES FILES 

Returns TRUE if the element of a compound device is a file path name. 

VERTICAL IMAGE EXTENT 

Returns the vertical (Y) source extent for images. 

VERTICAL VIDEO EXTENT 

Returns the vertical (Y) source extent for the video source. 

WINDOWS 

Not supported. 



WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returns immediately to the application. When the requested action 
is complete an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPABILITY (Digital Video Command) - Syntax Diagram 


CAPABILITY object 
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CAN PLAY 
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WAIT 
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CAPTURE 


CAPTURE (Digital Video Command) - Example 

capture digitalvideo at 100 100 260 220 convert wait 


CAPTURE (Digital Video Command) - Purpose 


The CAPTURE command captures the current video image. This does not cause the image or bitmap to be saved; the application must 
subsequently issue a SAVE command to save the device element. The device will freeze motion temporarily if needed to capture the image 
and put the image into the image device element. Repeated capture operations will overwrite the image contained in this temporary space. 
The device will wait for a SAVE command to transfer the information to a file. Use MCI_GETIMAGEBUFFER to supply an application with a 
copy of the capture video buffer. 

Note: If no rectangle is specified, the entire rectangle is captured. 


CAPTURE (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CAPTURE (Digital Video Command) Keyword - AT rect 


AT rect 

Specifies a rectangle relative to the window origin in device coordinates. The rectangle is specified as XI Y1 X2 Y2. The coordinates 
XI Y1 specify the lower-left corner and X2 Y2 specify the upper-right corner. Only the video in that subregion will be captured. 


CAPTURE (Digital Video Command) Keyword - CONVERT 


CONVERT 

Specifies that the image format will be converted to the OS/2 bitmap format. The default is the device-specific format. 


CAPTURE (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CAPTURE (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPTURE (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


AT rect 

Specifies a rectangle relative to the window origin in device coordinates. The rectangle is specified as XI Y1 X2 Y2. The coordinates 
XI Y1 specify the lower-left corner and X2 Y2 specify the upper-right corner. Only the video in that subregion will be captured. 

CONVERT 

Specifies that the image format will be converted to the OS/2 bitmap format. The default is the device-specific format. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPTURE (Digital Video Command) - Syntax Diagram 


CAPTURE 


object 


AT rect 
CONVERT 
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NOTIFY 


Examples 
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CONNECTOR 


CONNECTOR (Digital Video Command) - Example 


This enables video input connector number 2 on the capture adapter. 

connector digitalvideo enable type video in number 2 wait 


CONNECTOR (Digital Video Command) - Purpose 


The CONNECTOR command enables, disables, or queries the status of connector on a device. 


CONNECTOR (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 



Filename 

Alias 


CONNECTOR (Digital Video Command) Keyword - ENABLE 


ENABLE 

Enables information flow through the indicated connector. Use of this keyword requires that the NUMBER or TYPE keywords must 
also be specified. 


CONNECTOR (Digital Video Command) Keyword - DISABLE 


DISABLE 

Disables information flow through the indicated connector. Use of this keyword requires that the NUMBER or TYPE keywords must 
also be specified. 


CONNECTOR (Digital Video Command) Keyword - QUERY 


QUERY 

Queries the state of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled 
respectively. Use of this keyword requires that the NUMBER or TYPE keywords must also be specified. 


CONNECTOR (Digital Video Command) Keyword - NUMBER 
connector number 


NUMBER connectornumber 

Indicates the connector number on which to perform the requested action. If this item is omitted, then the first connector is assumed. 
If the TYPE item is included, then the connector number is interpreted as a relative offset within the specified connector type. 


CONNECTOR (Digital Video Command) Keyword - TYPE 
connector_type 


TYPE connector type 

Indicates the type of connector to which the requested action applies. The connector types are defined by each device. Valid 
connector type values for the digital video device include: 



line in 
video in 


CONNECTOR (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CONNECTOR (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTOR (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

ENABLE 

Enables information flow through the indicated connector. Use of this keyword requires that the NUMBER or TYPE keywords must 
also be specified. 

DISABLE 

Disables information flow through the indicated connector. Use of this keyword requires that the NUMBER or TYPE keywords must 
also be specified. 

QUERY 

Queries the state of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled 
respectively. Use of this keyword requires that the NUMBER or TYPE keywords must also be specified. 

NUMBER connectornumber 

Indicates the connector number on which to perform the requested action. If this item is omitted, then the first connector is assumed. 
If the TYPE item is included, then the connector number is interpreted as a relative offset within the specified connector type. 

TYPE connector type 

Indicates the type of connector to which the requested action applies. The connector types are defined by each device. Valid 
connector type values for the digital video device include: 

• line in 

■ video in 


WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 


application. 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTOR (Digital Video Command) - Syntax Diagram 
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NOTIFY 
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COPY 


COPY (Digital Video Command) - Example 


copy digitalvideo from 10000 to 50000 


COPY (Digital Video Command) - Purpose 



The COPY command copies information from a file into the clipboard. 


COPY (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


COPY (Digital Video Command) Keyword - FROM pos 


FROM pos 

The position to start copying. If FROM is omitted, the copy starts from the current position. If TO is omitted, the end of file is assumed. 
The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not specified. 


COPY (Digital Video Command) Keyword - TO pos 


TO pos 

The position to stop copying. If TO is omitted, the end of file is assumed. The position of the media will either be the from position if 
FROM is specified, or the previous position if FROM is not specified. 


COPY (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


COPY (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


COPY (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

FROM pos 

The position to start copying. If FROM is omitted, the copy starts from the current position. If TO is omitted, the end of file is assumed. 
The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not specified. 

TO pos 

The position to stop copying. If TO is omitted, the end of file is assumed. The position of the media will either be the from position if 
FROM is specified, or the previous position if FROM is not specified. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


COPY (Digital Video Command) - Syntax Diagram 


COPY 

object 

FROM pos 

WAIT 



TO pos 

NOTIFY 


Examples 


COPY (Digital Video Command) - Topics 


Select an item: 

Purpose 

Syntax Diagram 

Keywords 

Example 

Glossary 



CUE 


CUE (Digital Video Command) - Example 


The following command prepares the device for recording. 

cue digitalvideo input wait 

The following command prepares the device for playback and positions the media at the specified location, without displaying a video 
window. 

cue digitalvideo to 70 wait 


CUE (Digital Video Command) - Purpose 

The CUE command prepares for playback or recording. The CUE command does not have to be issued prior to playback or recording. 
However, depending on the device, it can reduce the delay associated with the PLAY or RECORD command. 

The CUE command is not related to the SETCUEPOINT command. 


CUE (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


CUE (Digital Video Command) Keyword - INPUT 


INPUT 

Prepares the device for recording. 


CUE (Digital Video Command) Keyword - OUTPUT 


OUTPUT 

Prepares the device for playback. This is the default. 


CUE (Digital Video Command) Keyword - NOSHOW 


NOSHOW 

Causes the window to be hidden while the cue operation is performed. This is the default. 


CUE (Digital Video Command) Keyword - SHOW 


SHOW 

Causes the window to be displayed while the cue operation is performed. 


CUE (Digital Video Command) Keyword - TO pos 


TO pos 

Specifies a position to seek to when cueing the device for playback. If the TO position is beyond the end of the media or segment, an 
MCIERR_OUTOFRANGE error is returned. The default TO position is 0 (the beginning of the media). 

If the STATUS command is issued following the CUE command to retrieve the current position, the position returned will indicate the 
next frame. 


CUE (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CUE (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CUE (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


INPUT 

Prepares the device for recording. 

OUTPUT 

Prepares the device for playback. This is the default. 

NOSHOW 

Causes the window to be hidden while the cue operation is performed. This is the default. 


SHOW 

Causes the window to be displayed while the cue operation is performed. 


TO pos 

Specifies a position to seek to when cueing the device for playback. If the TO position is beyond the end of the media or segment, an 
MCIERR_OUTOFRANGE error is returned. The default TO position is 0 (the beginning of the media). 

If the STATUS command is issued following the CUE command to retrieve the current position, the position returned will indicate the 
next frame. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CUE (Digital Video Command) - Syntax Diagram 


CUE object 

INPUT WAIT 

OUTPUT NOTIFY 

NOSHOW TO pos 

SHOW 


Examples 
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CUT (Digital Video Command) - Example 


cut digitalvideo from 10000 to 40000 wait 


CUT (Digital Video Command) - Purpose 


The CUT command cuts removes the specified range and places the data in the clipboard. 


CUT (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 


Device type 
Device name 
Filename 
Alias 


CUT (Digital Video Command) Keyword - FROM pos 


FROM pos 

The position to start cutting. If FROM is omitted, the cut starts from the current position. If TO is omitted, the end of file is assumed. 
The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not specified. 



CUT (Digital Video Command) Keyword - TO pos 


TO pos 

The position to stop cutting. If FROM is omitted, the cut starts from the current position. If TO is omitted, the end of file is assumed. 
The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not specified. 


CUT (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CUT (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


CUT (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

FROM pos 

The position to start cutting. If FROM is omitted, the cut starts from the current position. If TO is omitted, the end of file is assumed. 
The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not specified. 

TO pos 

The position to stop cutting. If FROM is omitted, the cut starts from the current position. If TO is omitted, the end of file is assumed. 
The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not specified. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


CUT (Digital Video Command) - Syntax Diagram 


CUT object 


FROM pos 
TO pos 


WAIT 

NOTIFY 


Examples 
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DELETE 


DELETE (Digital Video Command) - Example 


delete digitalvideo from 10000 to 40000 wait 


DELETE (Digital Video Command) - Purpose 


The DELETE command deletes information from a file. 



DELETE (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


DELETE (Digital Video Command) Keyword - FROM pos 


FROM pos 

The position to start deleting. If FROM is omitted, the delete starts from the current position. If TO is omitted, the end of file is 
assumed. The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not 
specified. 


DELETE (Digital Video Command) Keyword - TO pos 


TO pos 

The position to stop deleting. If FROM is omitted, the delete starts from the current position. If TO is omitted, the end of file is 
assumed. The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not 
specified. 


DELETE (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


DELETE (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


DELETE (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

The units of the TO and FROM positions must be supplied in the currently selected time format. 


FROM pos 

The position to start deleting. If FROM is omitted, the delete starts from the current position. If TO is omitted, the end of file is 
assumed. The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not 
specified. 

TO pos 

The position to stop deleting. If FROM is omitted, the delete starts from the current position. If TO is omitted, the end of file is 
assumed. The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not 
specified. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


DELETE (Digital Video Command) - Syntax Diagram 


DELETE object 


FROM pos 
TO pos 


WAIT 

NOTIFY 


Examples 
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INFO 


INFO (Digital Video Command) - Example 


info digitalvideo product wait 


INFO (Digital Video Command) - Purpose 


The INFO command fills a user-supplied buffer with information. 


INFO (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


INFO (Digital Video Command) Keyword - FILE 


FILE 

Returns the filename of the digital video file. 


INFO (Digital Video Command) Keyword - PRODUCT 


PRODUCT 

Returns the product name and model of the current digital video device. 



INFO (Digital Video Command) Keyword - REGION 


REGION 

Returns the name of the current tuner region. 


INFO (Digital Video Command) Keyword - REGION TEXT 


REGION TEXT 

Returns a description of the current tuner region. 


INFO (Digital Video Command) Keyword - WINDOW TEXT 


WINDOW TEXT 

Returns the caption of the display window. 


INFO (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


INFO (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


INFO (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


FILE 

Returns the filename of the digital video file. 

PRODUCT 

Returns the product name and model of the current digital video device. 

REGION 

Returns the name of the current tuner region. 

REGION TEXT 

Returns a description of the current tuner region. 

WINDOW TEXT 

Returns the caption of the display window. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


INFO (Digital Video Command) - Syntax Diagram 


INFO object FILE 

PRODUCT WAIT 

REGION NOTIFY 

REGION TEXT 
WINDOW TEXT 


Examples 
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LOAD 



LOAD (Digital Video Command) - Example 


load digitalvideo movie.avi wait 


LOAD (Digital Video Command) - Purpose 


The LOAD command loads a new device element (file) into an already open device context. 


LOAD (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


LOAD (Digital Video Command) Keyword - filename 


filename 

Specifies the name of the file to load. 


LOAD (Digital Video Command) Keyword - NEW 


NEW 

Creates a temporary element for subsequent use with the RECORD command (removing any previous cue input). The temporary file 
can be made permanent by providing a name using the SAVE command. 


LOAD (Digital Video Command) Keyword - READONLY 


READONLY 

Opens the file in a read-only mode and prevents inadvertent changes to the file. 


LOAD (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


LOAD (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


LOAD (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 

filename 

Specifies the name of the file to load. 


NEW 

Creates a temporary element for subsequent use with the RECORD command (removing any previous cue input). The temporary file 
can be made permanent by providing a name using the SAVE command. 


READONLY 

Opens the file in a read-only mode and prevents inadvertent changes to the file. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


LOAD (Digital Video Command) - Syntax Diagram 


LOAD 


object 


filename 


NEW 


WAIT 

READONLY NOTIFY 


Examples 
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OPEN 


OPEN (Digital Video Command) - Example 


open digitalvideo alias w shareable wait 


OPEN (Digital Video Command) - Purpose 


The OPEN command initializes the device. 


OPEN (Digital Video Command) Keyword - object 



object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


OPEN (Digital Video Command) Keyword - ALIAS 
device_alias 

ALIAS device_alias 

Specifies an alternate name for the device. If specified, it must also be used for subsequent references. 


OPEN (Digital Video Command) Keyword - DOSQUEUE 


DOSQUEUE 

If a device instance is opened with the DOSQUEUE keyword specified, window handles that are passed in for the instance will be 
treated as OS/2 Control Program queue handles. 


OPEN (Digital Video Command) Keyword - PARENT hwnd 


PARENT hwnd 

Specifies the window handle of the parent window as a character representation of the decimal window handle value. If specified, it is 
used as the parent window of the digital video device default window. 


OPEN (Digital Video Command) Keyword - READONLY 


READONLY 

Specifies that the file is to be opened in read-only mode. 


OPEN (Digital Video Command) Keyword - SHAREABLE 


SHAREABLE 

Initializes the device as shareable. Specifying SHAREABLE makes the resources of the device available to other device contexts. If 



SHAREABLE is not specified on OPEN, the resource will be exclusively acquired when the device is opened. 


OPEN (Digital Video Command) Keyword - TYPE device_type 


TYPE device_type 

Specifies the compound device used to control a device element. As an alternative to TYPE, the media control interface can use the 
.TYPE extended attribute or file extension associated with the file to select the controlling device. 


OPEN (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


OPEN (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


OPEN (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

ALIAS device_alias 

Specifies an alternate name for the device. If specified, it must also be used for subsequent references. 

DOSQUEUE 

If a device instance is opened with the DOSQUEUE keyword specified, window handles that are passed in for the instance will be 
treated as OS/2 Control Program queue handles. 

PARENT hwnd 

Specifies the window handle of the parent window as a character representation of the decimal window handle value. If specified, it is 
used as the parent window of the digital video device default window. 

READONLY 

Specifies that the file is to be opened in read-only mode. 


SHAREABLE 

Initializes the device as shareable. Specifying SHAREABLE makes the resources of the device available to other device contexts. If 
SHAREABLE is not specified on OPEN, the resource will be exclusively acquired when the device is opened. 

TYPE device_type 

Specifies the compound device used to control a device element. As an alternative to TYPE, the media control interface can use the 
.TYPE extended attribute or file extension associated with the file to select the controlling device. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


OPEN (Digital Video Command) - Syntax Diagram 


OPEN object 

ALIAS device_alias 

DOSQUEUE 

PARENT hwnd 

READONLY 

SHAREABLE 

TYPE device_type 


Examples 
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PASTE 


PASTE (Digital Video Command) - Example 



open digitalvideo alias videol shareable wait 

load videol movie.avi wait 

paste videol from 10000 to 40000 wait 


PASTE (Digital Video Command) - Purpose 


The PASTE command pastes information from the clipboard into a file. The media position after a paste operation is at the end of the pasted 
data. 


PASTE (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


PASTE (Digital Video Command) Keyword - FROM pos 


FROM pos 

The position to start pasting. If FROM is omitted, the paste starts at the current position. 


PASTE (Digital Video Command) Keyword - TO pos 


TO pos 

The position to stop pasting. The pasted data rep/aces the data from the FROM position (or the current position if FROM is not 
specified) to the TO position. 

If TO is omitted, the end of file is assumed and the pasted data is inserted starting at the FROM position (or the current position if 
FROM is not specified). 


PASTE (Digital Video Command) Keyword - WAIT 



WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


PASTE (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


PASTE (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

FROM pos 

The position to start pasting. If FROM is omitted, the paste starts at the current position. 

TO pos 

The position to stop pasting. The pasted data rep/aces the data from the FROM position (or the current position if FROM is not 
specified) to the TO position. 

If TO is omitted, the end of file is assumed and the pasted data is inserted starting at the FROM position (or the current position if 
FROM is not specified). 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


PASTE (Digital Video Command) - Syntax Diagram 


PASTE 


object 


FROM pos 
TO pos 


WAIT 

NOTIFY 


Examples 
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PLAY 


PLAY (Digital Video Command) - Example 


play digitalvideo notify 


PLAY (Digital Video Command) - Purpose 


The PLAY command starts a play operation on the device. 


PLAY (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


PLAY (Digital Video Command) Keyword - FROM pos 



FROM pos 

Specifies the frame at which to start playing. If FROM is omitted, PLAY starts at the current position. 


PLAY (Digital Video Command) Keyword - TO pos 


TO pos 

Specifies the frame at which to stop playing. If TO is omitted, PLAY stops at the end frame. 


PLAY (Digital Video Command) Keyword - FAST 


FAST 

Plays the digital video sequence at twice the normal recorded playback rate (no audio). 


PLAY (Digital Video Command) Keyword - SLOW 


SLOW 

Plays the digital video sequence at half the normal recorded playback rate (no audio). 


PLAY (Digital Video Command) Keyword - REVERSE 


REVERSE 

Indicates the play direction for the device is backwards. You cannot use the TO keyword with REVERSE. 


PLAY (Digital Video Command) Keyword - SCAN 


SCAN 

Plays frames when indexed. Otherwise, plays the digital video as fast as possible without disabling video (no audio). You cannot use 
the TO keyword with SCAN. 


PLAY (Digital Video Command) Keyword - SPEED units 



SPEED units 

Plays the digital video sequence at the specified speed. Speed is specified in units specified by set speed format. (See the SET 
command.) 


PLAY (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


PLAY (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


PLAY (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


FROM pos 

Specifies the frame at which to start playing. If FROM is omitted, PLAY starts at the current position. 

TO pos 

Specifies the frame at which to stop playing. If TO is omitted, PLAY stops at the end frame. 


FAST 

Plays the digital video sequence at twice the normal recorded playback rate (no audio). 

SLOW 

Plays the digital video sequence at half the normal recorded playback rate (no audio). 

REVERSE 

Indicates the play direction for the device is backwards. You cannot use the TO keyword with REVERSE. 


SCAN 

Plays frames when indexed. Otherwise, plays the digital video as fast as possible without disabling video (no audio). You cannot use 
the TO keyword with SCAN. 

SPEED units 

Plays the digital video sequence at the specified speed. Speed is specified in units specified by set speed format. (See the SET 
command.) 


WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


PLAY (Digital Video Command) - Syntax Diagram 


PLAY object 


FROM pos 
TO pos 


FAST 

SLOW 

REVERSE 

SCAN 

SPEED units 


WAIT 

NOTIFY 


Examples 


PLAY (Digital Video Command) - Remarks 


An MCIERR_OUTOFRANGE error is returned if the range specified with the FROM and TO keywords is not large enough. 

If you are using an application-defined window and your application is running on a system without direct-access device driver support for 
motion video, do not specify WAIT with the PLAY command unless the thread issuing the message is separate from the thread reading the 
message queue. 


PLAY (Digital Video Command) - Topics 
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PUT 



PUT (Digital Video Command) - Example 


The following command sets the monitor window position at 1 00, 1 00. 

put digitalvideo window at 100 100 260 220 move monitor wait 


The following command sets the video capture region to be a 640x288 rectangle at offset 0, 100 (from the lower left) out of the total video 
capture extents. 

put digitalvideo record source at 0 100 640 388 move wait 


The following command sets the output video size to 320x144. 

put digitalvideo record destination at 0 0 320 144 wait 


PUT (Digital Video Command) - Purpose 


The PUT command defines the source and destination windows. 


PUT (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


PUT (Digital Video Command) Keyword - DESTINATION AT 
rect 

DESTINATION AT rect 

Determines the size and position of the playback video relative to the playback window. The rectangle is relative to the window origin 
in device coordinates and is specified as XI Y1 X2 Y2. The coordinates XI Y1 specify the lower-left corner and X2 Y2 specify the 
upper-right corner. 



PUT (Digital Video Command) Keyword - WINDOW AT rect 


WINDOW AT rect 

Specifies the size and position of the playback window (either a default window or an application-defined window). 

Note: The MOVE and SIZE options can both be specified, in which case, the window is moved and sized at the same time. 


PUT (Digital Video Command) Keyword - MOVE 


MOVE 

Moves the appropriate window to the XI Y1 coordinates specified in the rectangle. Window coordinates are relative to the parent 
window. 

All coordinates of the rectangle (XI Y1 X2 Y2) must be specified, but X2 Y2 are ignored if the SIZE keyword is not specified. 

This option will not affect an application-supplied alternate video window. 


PUT (Digital Video Command) Keyword - SIZE 


SIZE 

Sizes the appropriate window to be (X2 - XI) and (Y2 - Y1). All coordinates of the rectangle (XI Y1 X2 Y2) must be specified. 
This option will not affect an application-supplied alternate video window. 


PUT (Digital Video Command) Keyword - MONITOR 


MONITOR 

Specifies the position and size of the window containing the monitor rectangle. 

Note: The MOVE and SIZE options can both be specified, in which case, the monitor video window is moved and sized at the same 
time. 


PUT (Digital Video Command) Keyword - RECORD 
DESTINATION AT rect 


RECORD DESTINATION AT rect 

Determines the size of the movie to be played back (playback video). The XI and Y1 rectangle coordinates are subtracted from X2 
and Y2, respectively, to determine the playback video size. For example, the following command: 



PUT object RECORD DESTINATION AT 13 47 173 167 


yields a playback video size of 1 60x1 20 ((1 73 - 1 3)x(1 67 - 47)). 

If either the width or the height of the rectangle specified with the RECORD and DESTINATION keywords (indicating playback video 
size) is not a multiple of eight, that value is rounded to the nearest multiple of eight. 

Use the WHERE object RECORD DESTINATION ADJUSTED command to obtain the actual size of the playback video. 


PUT (Digital Video Command) Keyword - RECORD SOURCE 
AT rect 


RECORD SOURCE AT rect 

Specifies the origin and size of a window describing video to be captured relative to the maximum available capture window. The 
rectangle coordinates for source capture are relative to the lower-left corner of the video source. 

If the device is cued for input (recording), the actual source rectangle is displayed. Otherwise, the maximum source rectangle is 
displayed with any subset represented as an animated, dashed-line rectangle. 

Note: If only the source is set then the destination defaults to half of the source size. The video source extent can be found using the 
STATUS command with the HORIZONTAL VIDEO EXTENT and VERTICAL VIDEO EXTENT keywords. 

If the device cannot distort and the rectangle specified with PUT object RECORD SOURCE AT rect is not an integral multiple of the 
rectangle specified with PUT object RECORD DESTINATION AT rect (playback video size), the source and destination rectangles 
will be adjusted to find the nearest values that will make the source become an integral multiple of the destination and the destination 
become a multiple of eight. 


PUT (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


PUT (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


PUT (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

DESTINATION AT rect 

Determines the size and position of the playback video 
in device coordinates and is specified as XI Y1 X2 Y2. 
upper-right corner. 

WINDOW AT rect 

Specifies the size and position of the playback window 
Note: The MOVE and SIZE options can both be specified, in which case, the window is moved and sized at the same time. 

MOVE 

Moves the appropriate window to the XI Y1 coordinates specified in the rectangle. Window coordinates are 
relative to the parent window. 

All coordinates of the rectangle (XI Y1 X2 Y2) must be specified, but X2 Y2 are ignored if the SIZE keyword is not 
specified. 

This option will not affect an application-supplied alternate video window. 

SIZE 

Sizes the appropriate window to be (X2 - XI) and (Y2 - Y1). All coordinates of the rectangle (XI Y1 X2 Y2) must be 
specified. 

This option will not affect an application-supplied alternate video window. 


relative to the playback window. The rectangle is relative to the window origin 
The coordinates XI Y1 specify the lower-left corner and X2 Y2 specify the 


(either a default window or an application-defined window). 


MONITOR 

Specifies the position and size of the window containing the monitor rectangle. 

Note: The MOVE and SIZE options can both be specified, in which case, the monitor video window is moved and 
sized at the same time. 

RECORD DESTINATION AT rect 

Determines the size of the movie to be played back (playback video). The XI and Y1 rectangle coordinates are subtracted from X2 
and Y2, respectively, to determine the playback video size. For example, the following command: 

PUT object RECORD DESTINATION AT 13 47 173 167 


yields a playback video size of 1 60x1 20 ((1 73 - 1 3)x(1 67 - 47)). 

If either the width or the height of the rectangle specified with the RECORD and DESTINATION keywords (indicating playback video 
size) is not a multiple of eight, that value is rounded to the nearest multiple of eight. 

Use the WHERE object RECORD DESTINATION ADJUSTED command to obtain the actual size of the playback video. 

RECORD SOURCE AT rect 

Specifies the origin and size of a window describing video to be captured relative to the maximum available capture window. The 
rectangle coordinates for source capture are relative to the lower-left corner of the video source. 

If the device is cued for input (recording), the actual source rectangle is displayed. Otherwise, the maximum source rectangle is 
displayed with any subset represented as an animated, dashed-line rectangle. 

Note: If only the source is set then the destination defaults to half of the source size. The video source extent can be found using the 
STATUS command with the HORIZONTAL VIDEO EXTENT and VERTICAL VIDEO EXTENT keywords. 

If the device cannot distort and the rectangle specified with PUT object RECORD SOURCE AT rect is not an integral multiple of the 
rectangle specified with PUT object RECORD DESTINATION AT rect (playback video size), the source and destination rectangles 
will be adjusted to find the nearest values that will make the source become an integral multiple of the destination and the destination 
become a multiple of eight. 


Note: The source rectangle specifies the portion of the image to be captured and the destination rectangle specifies the size of the video to 
be recorded. This indicates the scaling to be applied to the source rectangle. 


WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


PUT (Digital Video Command) - Syntax Diagram 


PUT object DESTINATION AT rect MOVE 

WINDOW AT rect SIZE MONITOR 

RECORD DESTINATION AT rect 
RECORD SOURCE AT rect 


WAIT 

NOTIFY 


Examples 


PUT (Digital Video Command) - Topics 
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RECORD 


RECORD (Digital Video Command) - Example 


record digitalvideo to 1000 wait 



RECORD (Digital Video Command) - Purpose 


The RECORD command initiates real-time recording of motion video with audio capture. 

The functionality of video record, capture, and monitor is performed through an media control interface logical device. An association 
between a logical device name and any video capture cards is established automatically during installation. D/gita/vic/eoOl is the logical 
device that supports playback only, with unmodified functionality from the original OS/2 multimedia installation, and is not associated with a 
capture device. DigitaMc/eo02 (and higher) enables capture and recording, and is associated with capture hardware. These logical device 
names are produced by default through installation of OS/2 multimedia and Video IN for OS/2. 

Note: Only a single actively recording instance is supported at a time, as video capture hardware does not support concurrent use. Multiple 
instances of the MOD can be opened, but only one recording instance can be open. 


RECORD (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


RECORD (Digital Video Command) Keyword - TO pos 


TO pos 

Specifies the position to stop recording. TO is used only as an indication of the length of the recording to be performed. A STOP is 
performed implicitly if the device is not stopped when RECORD is issued. 


RECORD (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


RECORD (Digital Video Command) Keyword - NOTIFY 


NOTIFY 



The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


RECORD (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


TO pos 

Specifies the position to stop recording. TO is used only as an indication of the length of the recording to be performed. A STOP is 
performed implicitly if the device is not stopped when RECORD is issued. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


RECORD (Digital Video Command) - Syntax Diagram 


RECORD object 


TO pos 


WAIT 

NOTIFY 


Examples 


RECORD (Digital Video Command) - Topics 
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REDO 



REDO (Digital Video Command) - Example 


open macaw.avi alias vid shareable wait 
cut vid to 6000 wait 
undo vid wait 
redo vid wait 


REDO (Digital Video Command) - Purpose 


The REDO command redoes the last editing action (cut, paste, or delete) which was undone with the UNDO command. REDO should 
immediately follow UNDO; otherwise, editing actions performed after UNDO (and before a corresponding REDO) will be lost when the 
REDO command is issued. The position of the media after a REDO is 0. 

Multiple REDO operations are permitted, corresponding to the number of editing operations that have been previously undone with the 
UNDO command. 


REDO (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


REDO (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


REDO (Digital Video Command) Keyword - NOTIFY 


NOTIFY 


The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


REDO (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


REDO (Digital Video Command) - Syntax Diagram 


REDO object 


WAIT 

NOTIFY 


Examples 


REDO (Digital Video Command) - Topics 
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REWIND 



REWIND (Digital Video Command) - Example 


rewind digitalvideo wait 


REWIND (Digital Video Command) - Purpose 


The REWIND command rewinds or seeks the device element to the first playable position (beginning). 


REWIND (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


REWIND (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


REWIND (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


REWIND (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


REWIND (Digital Video Command) - Syntax Diagram 


REWIND object 


WAIT 

NOTIFY 


Examples 


REWIND (Digital Video Command) - Topics 
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SAVE 


SAVE (Digital Video Command) - Example 


save videol mymovie.avi wait 



SAVE (Digital Video Command) - Purpose 


The SAVE command saves the current file. 


SAVE (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


SAVE (Digital Video Command) Keyword - filename 


filename 

Specifies the destination path and file name. 


SAVE (Digital Video Command) Keyword - VIDEO 


VIDEO 

The file to be saved is a video file. This is the default. 


SAVE (Digital Video Command) Keyword - IMAGE 


IMAGE 

The file to be saved is a still image file. 


SAVE (Digital Video Command) Keyword - WAIT 


WAIT 



The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SAVE (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SAVE (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

filename 

Specifies the destination path and file name. 

Specifying VIDEO is accepted but not required. Saving a video file is the default. 


VIDEO 

The file to be saved is a video file. This is the default. 

IMAGE 

The file to be saved is a still image file. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MMJVIC I NOTIFY message is sent to the application window procedure. 


SAVE (Digital Video Command) - Syntax Diagram 


SAVE object filename 


VIDEO 

IMAGE 


WAIT 

NOTIFY 


Examples 



SAVE (Digital Video Command) - Topics 
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SEEK 


SEEK (Digital Video Command) - Example 


seek digitalvideo to start wait 


SEEK (Digital Video Command) - Purpose 


The SEEK command seeks finds the specified position in the file. 


SEEK (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


SEEK (Digital Video Command) Keyword - TO pos 


TO pos 

Specifies the final position for the seek. 


SEEK (Digital Video Command) Keyword - TO NEAREST pos 


TO NEAREST pos 

Seeks to the nearest l-frame preceding the point specified by pos. 


SEEK (Digital Video Command) Keyword - TO START 


TO START 

Seeks to the start of the file. 


SEEK (Digital Video Command) Keyword - TO END 


TO END 

Seeks to the end of the file. 


SEEK (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SEEK (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SEEK (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


TO pos 

Specifies the final position for the seek. 

TO NEAREST pos 

Seeks to the nearest l-frame preceding the point specified by pos. 

TO START 

Seeks to the start of the file. 

TO END 

Seeks to the end of the file. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SEEK (Digital Video Command) - Syntax Diagram 


SEEK object 


TO 

pos 


TO 

NEAREST pos 

WAIT 

TO 

START 

NOTIFY 

TO 

END 



Examples 


SEEK (Digital Video Command) - Topics 
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SET 



SET (Digital Video Command) - Example 


set digitalvideo time format milliseconds wait 


SET (Digital Video Command) - Purpose 


The SET command sets the various control and attribute items. 


SET (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


SET (Digital Video Command) Keyword - AUDIO 


AUDIO 

Specifies the audio attributes of the device context determined by the ALL, LEFT, RIGFIT, OVER, and VOLUME keywords. 


SET (Digital Video Command) Keyword - ALL 


ALL 

Applies to both or all of the channels (default). 
Specify ON or OFF with the ALL keyword. 


SET (Digital Video Command) Keyword - ON 



ON 


Enables audio. 


SET (Digital Video Command) Keyword - OFF 


OFF 

Disables audio. 


SET (Digital Video Command) Keyword - LEFT 


LEFT 

Applies to the left channel. 

Specify ON or OFF with the LEFT keyword. 


SET (Digital Video Command) Keyword - ON 


ON 

Enables audio for the left channel. 


SET (Digital Video Command) Keyword - OFF 


OFF 

Disables audio for the left channel. 


SET (Digital Video Command) Keyword - RIGHT 


RIGHT 

Applies to the right channel. 

Specify ON or OFF with the RIGFIT keyword. 



SET (Digital Video Command) Keyword - ON 


ON 

Enables audio for the right channel. 


SET (Digital Video Command) Keyword - OFF 


OFF 

Disables audio for the right channel. 


SET (Digital Video Command) Keyword - OVER milliseconds 


OVER milliseconds 

Applies the change over the specified time period (fade). 


SET (Digital Video Command) Keyword - VOLUME 
percentage 


VOLUME percentage 

Sets the volume level. 


SET (Digital Video Command) Keyword - AUDIOSYNC value 


AUDIOSYNC value 

Sets the audio synchronization value, where va/ue is the MMTIME value to adjust audio time ahead relative to video time. 


SET (Digital Video Command) Keyword - FORWARD 


FORWARD 



Sets the audio synchronization value, where va/ue is the MMTIME value to adjust audio time ahead relative to video time. 


SET (Digital Video Command) Keyword - REVERSE 


REVERSE 

Sets the audio synchronization value, where va/ue is the MMTIME value to adjust audio time back relative to video time. 


SET (Digital Video Command) Keyword - BRIGHTNESS level 


BRIGHTNESS level 

Sets the capture card brightness to the specified level (0 - 1 00). The default value is determined by the user through the Setup 
application; if no value is set by the user in the Setup, a default provided by the particular device-specific physical device driver is 
used. 


SET (Digital Video Command) Keyword - CHANNELS integer 

CHANNELS integer 

Sets the number of channels in the audio soundtrack recording (1 = mono, 2 = stereo). The default setting is 1. 


SET (Digital Video Command) Keyword - CONTRAST level 


CONTRAST level 

Sets the capture card contrast to the specified level (0 - 1 00). The default value is determined by the user through the Setup 
application; if no value is set by the user in the Setup, a default provided by the particular device-specific physical device driver is 
used. 


SET (Digital Video Command) Keyword - HUE level 


HUE level 

Sets the capture card hue to the specified level (0 - 100). where 0 is maximum green, 100 is maximum red, and 50 is neutral. The 
default value is determined by the user through the Setup application; if no value is set by the user in the Setup, a default provided by 
the particular device-specific physical device driver is used. 



SET (Digital Video Command) Keyword - GRAPHIC COLOR 
integer 


GRAPHIC COLOR integer 

Sets the transparent color used as the "chroma-key" on video overlay hardware (has the same effect as specifying the 
TRANSPARENT COLOR integer). The color is set as a numeric value in the range 0 - (/7-1) where n represents the number of 
colors available. This value only pertains to video overlay devices, such as Video Blaster. 

The default value is determined by the user through the Setup page for the digital video device; if a default value is not set by the 
user, 0x2D becomes the default. 


SET (Digital Video Command) Keyword - MONITOR state 


MONITOR state 

Sets monitoring as specified by state. When monitoring is turned on, a monitor window is created. The monitor window is similar to 
that of the playback window. Valid state values are: 

on Enables monitoring, 

off Disables monitoring. 


SET (Digital Video Command) Keyword - RECORD AUDIO 
ON 


RECORD AUDIO ON 

Enables audio soundtrack recording. This is the default. 


SET (Digital Video Command) Keyword - RECORD AUDIO 
OFF 


RECORD AUDIO OFF 

Disables audio soundtrack recording. 


SET (Digital Video Command) Keyword - REFERENCE 
FRAME INTERVAL n 



REFERENCE FRAME INTERVAL n 

Sets the reference frame interval where n refers to a reference frame (l-frame) being inserted every nth frame. A value of 0 results in 
no l-frames, 1 causes every frame to be an l-frame, 2 causes every other frame to be an l-frame, and so on. Although there is no 
upper bound on the reference frame interval, a reference frame interval that does not exceed two seconds produces the best results. 
The default reference frame interval is every 1 5th frame (once a second at the default frame rate of 1 5 frames per second). 


SET (Digital Video Command) Keyword - SATURATION level 


SATURATION level 

Sets the capture card saturation to the specified level (0 - 100). The default value is determined by the user through the Setup 
application; if no value is set by the user in the Setup, a default provided by the particular device-specific physical device driver is 
used. 


SET (Digital Video Command) Keyword - SAMPLESPERSEC 
integer 


SAMPLESPERSEC integer 

Sets the number of waveform samples per second in the audio soundtrack recording. This value is usually 1 1 025, 22050, or 441 00. 
The default is 11025. 


SET (Digital Video Command) Keyword - SPEED FORMAT 
PERCENTAGE 


SPEED FORMAT PERCENTAGE 

Sets the speed format to percentage (playback only). 


SET (Digital Video Command) Keyword - SPEED FORMAT 
FPS 


SPEED FORMAT FPS 

Sets the speed format to frames per second (playback only). 


SET (Digital Video Command) Keyword - TIME FORMAT 
MILLISECONDS 



TIME FORMAT MILLISECONDS 

Sets the time format to milliseconds. All position information is this format following this command. You can abbreviate milliseconds 
as ms. 


SET (Digital Video Command) Keyword - TIME FORMAT 
MMTIME 


TIME FORMAT MMTIME 

Sets the time format to MMTIME. 


SET (Digital Video Command) Keyword - TIME FORMAT 
FRAMES 


TIME FORMAT FRAMES 

Sets time format to frames. All position information is specified in frames following this command. When the device is opened, 
frames is the default mode. 


SET (Digital Video Command) Keyword - TIME FORMAT 
HMS 


TIME FORMAT HMS 

Sets time format to Hours, Minutes, Seconds. All position information is this format following this command. 


SET (Digital Video Command) Keyword - TIME FORMAT 
HMSF 


TIME FORMAT HMSF 

Sets time format to Hours, Minutes, Seconds, and Frames. All position information is this format following this command. 


SET (Digital Video Command) Keyword - TRANSPARENT 



COLOR integer 


TRANSPARENT COLOR integer 

Sets the transparent color used as the "chroma-key" on video overlay hardware (has the same effect as specifying GRAPH/C 
COLOR integer). The color is set as a numeric value in the range 0 - (/7-1) where n represents the number of colors available. This 
value only pertains to video overlay devices, such as Video Blaster. 

The default value is determined by the user through the Setup page for the digital video device; if a default value is not set by the 
user, 0x2D becomes the default. 


SET (Digital Video Command) Keyword - VIDEO 
COMPRESSION fourcc 


VIDEO COMPRESSION fourcc 

Specifies the FOURCC compression type used for recording motion video. Only symmetric compressors will be enabled for real-time 
recording. Possible types include: 


DIB 

Raw (uncompressed format) 

ULTI 

Ultimotion 

RT21 

Indeo 2.1 

IV31 

Indeo 3.1 


Note: Compressors are not available for FLIC, MPEG, and Indeo 3.2 in this version of OS/2. 


SET (Digital Video Command) Keyword - VIDEO RECORD 
RATE frames per second 


VIDEO RECORD RATE frames per second 

Sets the frame rate for recording as an integral number of frames per second. This sets the target record rate, but there is no 
guarantee this rate will be attained. Drop frame records will be inserted into the output data stream to indicate frames dropped during 
the record process. The default record frame is rate 15 frames per second. 


SET (Digital Video Command) Keyword - VIDEO RECORD 
FRAME DURATION integer 


VIDEO RECORD FRAME DURATION integer 

Sets the frame rate for recording as the time duration of each frame in microseconds. This is useful for setting non-integer frame 
rates; for example, 12.5 frames per second of a PAL videodisc: 1000000/12.5 = 80000 microseconds. The default frame duration is 
66,667 microseconds, equivalent to 1 5 frames per second. The maximum frame duration is 1 ,000,000 microseconds (1 frame per 
second), and the minimum frame duration is 33,333 microseconds (30 frames per second). 



SET (Digital Video Command) Keyword - VIDEO QUALITY 
level 


VIDEO QUALITY level 

Sets the compression quality level setting to be sent to the CODEC. This value is in the range 0 - 10,000. Not all CODECs support 
quality level settings. The default setting for video quality is 5000. 


SET (Digital Video Command) Keyword - VIDEO COLOR 
integer 


VIDEO COLOR integer 

Sets transparency color for transparency in video on dual-plane video adapters such as RealMagic. Graphics will be seen wherever 
the transparency color appears in the video. The color is set as a numeric value in the range 0...(/7 - 1). Where n represents the 
number of available colors. 


SET (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SET (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SET (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


AUDIO 


Specifies the audio attributes of the device context determined by the ALL, LEFT, RIGFIT, OVER, and VOLUME keywords. 

ALL 


Applies to both or all of the channels (default). 
Specify ON or OFF with the ALL keyword. 

ON 

Enables audio. 

OFF 


Disables audio. 


LEFT 


Applies to the left channel. 

Specify ON or OFF with the LEFT keyword. 


ON 

OFF 


Enables audio for the left channel. 
Disables audio for the left channel. 


RIGHT 


Applies to the right channel. 

Specify ON or OFF with the RIGFIT keyword. 


ON 

OFF 


Enables audio for the right channel. 
Disables audio for the right channel. 


OVER milliseconds 

Applies the change over the specified time period (fade). 

VOLUME percentage 

Sets the volume level. 


AUDIOSYNC value 

Sets the audio synchronization value, where va/ue is the MMTIME value to adjust audio time ahead relative to video time. 

FORWARD 

Sets the audio synchronization value, where va/ue is the MMTIME value to adjust audio time ahead relative to 
video time. 

REVERSE 

Sets the audio synchronization value, where va/ue is the MMTIME value to adjust audio time back relative to video 
time. 

BRIGHTNESS level 

Sets the capture card brightness to the specified level (0 - 1 00). The default value is determined by the user through the Setup 
application; if no value is set by the user in the Setup, a default provided by the particular device-specific physical device driver is 
used. 

CHANNELS integer 

Sets the number of channels in the audio soundtrack recording (1 = mono, 2 = stereo). The default setting is 1. 

CONTRAST level 

Sets the capture card contrast to the specified level (0 - 1 00). The default value is determined by the user through the Setup 
application; if no value is set by the user in the Setup, a default provided by the particular device-specific physical device driver is 
used. 

HUE level 

Sets the capture card hue to the specified level (0 - 100). where 0 is maximum green, 100 is maximum red, and 50 is neutral. The 
default value is determined by the user through the Setup application; if no value is set by the user in the Setup, a default provided by 
the particular device-specific physical device driver is used. 

GRAPHIC COLOR integer 

Sets the transparent color used as the "chroma-key" on video overlay hardware (has the same effect as specifying the 



TRANSPARENT COLOR integer). The color is set as a numeric value in the range 0 - (/7-1) where n represents the number of 
colors available. This value only pertains to video overlay devices, such as Video Blaster. 

The default value is determined by the user through the Setup page for the digital video device; if a default value is not set by the 
user, 0x2D becomes the default. 

MONITOR state 

Sets monitoring as specified by state. When monitoring is turned on, a monitor window is created. The monitor window is similar to 
that of the playback window. Valid state values are: 

on Enables monitoring, 

off Disables monitoring. 

RECORD AUDIO ON 

Enables audio soundtrack recording. This is the default. 

RECORD AUDIO OFF 

Disables audio soundtrack recording. 

REFERENCE FRAME INTERVAL n 

Sets the reference frame interval where n refers to a reference frame (l-frame) being inserted every nth frame. A value of 0 results in 
no l-frames, 1 causes every frame to be an l-frame, 2 causes every other frame to be an l-frame, and so on. Although there is no 
upper bound on the reference frame interval, a reference frame interval that does not exceed two seconds produces the best results. 
The default reference frame interval is every 1 5th frame (once a second at the default frame rate of 1 5 frames per second). 

SATURATION level 

Sets the capture card saturation to the specified level (0 - 100). The default value is determined by the user through the Setup 
application; if no value is set by the user in the Setup, a default provided by the particular device-specific physical device driver is 
used. 

SAMPLESPERSEC integer 

Sets the number of waveform samples per second in the audio soundtrack recording. This value is usually 1 1 025, 22050, or 441 00. 
The default is 11025. 

SPEED FORMAT PERCENTAGE 

Sets the speed format to percentage (playback only). 

SPEED FORMAT FPS 

Sets the speed format to frames per second (playback only). 

TIME FORMAT MILLISECONDS 

Sets the time format to milliseconds. All position information is this format following this command. You can abbreviate milliseconds 
as ms. 

TIME FORMAT MMTIME 

Sets the time format to MMTIME. 

TIME FORMAT FRAMES 

Sets time format to frames. All position information is specified in frames following this command. When the device is opened, 
frames is the default mode. 

TIME FORMAT HMS 

Sets time format to Hours, Minutes, Seconds. All position information is this format following this command. 

TIME FORMAT HMSF 

Sets time format to Hours, Minutes, Seconds, and Frames. All position information is this format following this command. 

TRANSPARENT COLOR integer 

Sets the transparent color used as the "chroma-key" on video overlay hardware (has the same effect as specifying GRAPH/C 
COLOR integer). The color is set as a numeric value in the range 0 - (/7-1) where n represents the number of colors available. This 
value only pertains to video overlay devices, such as Video Blaster. 

The default value is determined by the user through the Setup page for the digital video device; if a default value is not set by the 
user, 0x2D becomes the default. 

VIDEO COMPRESSION fourcc 

Specifies the FOURCC compression type used for recording motion video. Only symmetric compressors will be enabled for real-time 
recording. Possible types include: 


DIB 

Raw (uncompressed format) 

ULTI 

Ultimotion 

RT21 

Indeo 2.1 

IV31 

Indeo 3.1 



Note: Compressors are not available for FLIC, MPEG, and Indeo 3.2 in this version of OS/2. 

VIDEO RECORD RATE frames per second 

Sets the frame rate for recording as an integral number of frames per second. This sets the target record rate, but there is no 
guarantee this rate will be attained. Drop frame records will be inserted into the output data stream to indicate frames dropped during 
the record process. The default record frame is rate 15 frames per second. 

VIDEO RECORD FRAME DURATION integer 

Sets the frame rate for recording as the time duration of each frame in microseconds. This is useful for setting non-integer frame 
rates; for example, 12.5 frames per second of a PAL videodisc: 1000000/12.5 = 80000 microseconds. The default frame duration is 
66,667 microseconds, equivalent to 1 5 frames per second. The maximum frame duration is 1 ,000,000 microseconds (1 frame per 
second), and the minimum frame duration is 33,333 microseconds (30 frames per second). 

VIDEO QUALITY level 

Sets the compression quality level setting to be sent to the CODEC. This value is in the range 0 - 10,000. Not all CODECs support 
quality level settings. The default setting for video quality is 5000. 

VIDEO COLOR integer 

Sets transparency color for transparency in video on dual-plane video adapters such as RealMagic. Graphics will be seen wherever 
the transparency color appears in the video. The color is set as a numeric value in the range 0...(/7 - 1). Where n represents the 
number of available colors. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


SET (Digital Video Command) - Syntax Diagram 

SET object AUDIO 


ALL 

ON 


OFF 

LEFT 

ON 


OFF 

RIGHT 

ON 


OFF 


OVER milliseconds 
VOLUME percentage 

AUDIOSYNC value 

FORWARD 

REVERSE 

BITSPERSAMPLE integer 
BRIGHTNESS level 
CHANNELS integer 
CONTRAST level 
GRAPHIC COLOR integer 
HUE level 
MONITOR state 
RECORD AUDIO ON 
RECORD AUDIO OFF 
REFERENCE FRAME INTERVAL n 
SATURATION level 
SAMPLESPERSEC integer 
SPEED FORMAT PERCENTAGE 
SPEED FORMAT FPS 
TIME FORMAT MILLISECONDS 
TIME FORMAT MMTIME 
TIME FORMAT FRAMES 
TIME FORMAT HMS 
TIME FORMAT HMSF 
TRANSPARENT COLOR integer 
VIDEO COMPRESSION fourcc 


VIDEO RECORD RATE frames per second 
VIDEO RECORD FRAME DURATION integer 
VIDEO QUALITY level 
VIDEO COLOR integer 


WAIT 

NOTIFY 


Examples 
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SETTUNER 


SETTUNER (Digital Video Command) - Example 


settuner digitalvideo03 region usacatv tv channel 29 


SETTUNER (Digital Video Command) - Purpose 


The SETTUNER command causes the MCD to change the frequency that the tuner device is tuned to. 


SETTUNER (Digital Video Command) Keyword - object 


object 


Object associated with this media control interface command. The object can be one of the following: 



Device type 
Device name 
Filename 
Alias 


SETTUNER (Digital Video Command) Keyword - TV 
CHANNEL integer 


TV CHANNEL integer 

Sets the channel to the value specified by integer. Channel is used along with region and fine-tuning values to calculate the 
frequency. 


SETTUNER (Digital Video Command) Keyword - REGION 
name 


REGION name 

Sets the region to the value specified by name. Region is used along with channel and fine-tuning values to calculate the frequency. 


SETTUNER (Digital Video Command) Keyword - FINETUNE 


FINETUNE 

Use the PLUS or MINUS keyword with FINETUNE to indicate whether the fine-tuning value is positive or negative. Fine-tuning is 
used along with region and channel values to calculate the frequency. 


SETTUNER (Digital Video Command) Keyword - PLUS 
integer 


PLUS integer 

Indicates a positive fine-tuning value. 


SETTUNER (Digital Video Command) Keyword - MINUS 
integer 



MINUS integer 

Indicates a negative fine-tuning value. 


SETTUNER (Digital Video Command) Keyword - 
FREQUENCY integer 


FREQUENCY integer 

Sets the frequency being sent to the device driver to the value specified by integer. Using the FREQUENCY keyword to directly set 
the frequency overrides channel, region, and fine-tuning values. 


SETTUNER (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SETTUNER (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SETTUNER (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

TV CHANNEL integer 

Sets the channel to the value specified by integer. Channel is used along with region and fine-tuning values to calculate the 
frequency. 

REGION name 

Sets the region to the value specified by name. Region is used along with channel and fine-tuning values to calculate the frequency. 

FINETUNE 

Use the PLUS or MINUS keyword with FINETUNE to indicate whether the fine-tuning value is positive or negative. Fine-tuning is 
used along with region and channel values to calculate the frequency. 


PLUS integer 

Indicates a positive fine-tuning value. 

MINUS integer 

Indicates a negative fine-tuning value. 

FREQUENCY integer 

Sets the frequency being sent to the device driver to the value specified by integer. Using the FREQUENCY keyword to directly set 
the frequency overrides channel, region, and fine-tuning values. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SETTUNER (Digital Video Command) - Syntax Diagram 


SETTUNER object 

TV CHANNEL integer 
REGION name 

FINETUNE PLUS integer 

MINUS integer 


FREQUENCY integer WAIT 

NOTIFY 
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STATUS 



STATUS (Digital Video Command) - Example 


status digitalvideo clipboard wait 


STATUS (Digital Video Command) - Purpose 


The STATUS command obtains status information for the device. 


STATUS (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


STATUS (Digital Video Command) Keyword - AUDIOSYNC 


AUDIOSYNC 

Returns the audio synchronization adjust value. This value is always expressed in MMTIME units. The default value is 0. 


STATUS (Digital Video Command) Keyword - AUDIOSYNC 
DIRECTION 


AUDIOSYNC DIRECTION 

Returns the direction of the adjustment in audio synchronization. This is forward of backward relative to video time. The default is 
forward. 


STATUS (Digital Video Command) Keyword - 



BITSPERSAMPLE 


BITSPERSAMPLE 

Returns the currently set bits per sample used for playing, recording, and saving. 


STATUS (Digital Video Command) Keyword - BRIGHTNESS 


BRIGHTNESS 

Returns the brightness level. 


STATUS (Digital Video Command) Keyword - CHANNELS 


CHANNELS 

Returns the currently set channel count used for playing, recording, and saving. 


STATUS (Digital Video Command) Keyword - CLIPBOARD 


CLIPBOARD 

Returns TRUE if compatible data is in the clipboard; otherwise, returns FALSE. 


STATUS (Digital Video Command) Keyword - CONTRAST 


CONTRAST 

Returns the contrast level. 


STATUS (Digital Video Command) Keyword - CURRENT 
TRACK 


CURRENT TRACK 

Returns the current track. 



STATUS (Digital Video Command) Keyword - 
DROPPEDFRAMEPCT 


DROPPEDFRAMEPCT 

Returns the percentage of dropped frames for playback or recording operations. The value returned is in the range 0-100, where a 
value of 0 indicates that no frame drops are occurring or have occurred. A value of 100 indicates that all frames are being dropped or 
have been dropped. 

This STATUS value can be queried during a recording operation to obtain the cumulative drops that have occurred since recording 
began. This value can also be queried during a playback operation to obtain the cumulative frame drops that have occurred since 
playback began or was resumed after a seek, pause, or stop. If the value is queried when the device is stopped, the percentage of 
dropped frames accumulated at the end of the last playback or recording operation that was performed is returned. 

A value of 0 is returned if no playback or recording operations have been performed, the device is seeking or has been seeked, or the 
device is playing in scan mode. 


STATUS (Digital Video Command) Keyword - GRAPHIC 
COLOR 


GRAPHIC COLOR 

Returns the value of the transparent color used as the "chroma-key" on video overlay hardware. 


STATUS (Digital Video Command) Keyword - HORIZONTAL 
IMAGE EXTENT 


HORIZONTAL IMAGE EXTENT 

Not supported. 


STATUS (Digital Video Command) Keyword - HORIZONTAL 
VIDEO EXTENT 


HORIZONTAL VIDEO EXTENT 

Returns the horizontal (X) extent of the currently loaded motion video. 


STATUS (Digital Video Command) Keyword - HUE 



HUE 


Returns the hue level. 


STATUS (Digital Video Command) Keyword - FORMAT TAG 


FORMAT TAG 

Returns WAVE_FORMAT_PCM, the only format currently supported by the digital video device. However, if a movie is loaded that 
contains a format other than PCM, the format used in the movie will be returned. 


STATUS (Digital Video Command) Keyword - FORWARD 


FORWARD 

Returns TRUE if the play direction is forward or if the device is not playing. 


STATUS (Digital Video Command) Keyword - IMAGE 
BITSPERPEL 


IMAGE BITSPERPEL 

Returns the number of bits per pel for saving bit maps. 


STATUS (Digital Video Command) Keyword - IMAGE 
PELFORMAT 


IMAGE PELFORMAT 

Returns the pel format for saving bit maps or images. 


STATUS (Digital Video Command) Keyword - LENGTH 


LENGTH 

Returns the length in the current time format. 



STATUS (Digital Video Command) Keyword - LENGTH 
TRACK track number 


LENGTH TRACK track_number 

Returns the total number of frames in the track specified by track_number. 


STATUS (Digital Video Command) Keyword - MEDIA 
PRESENT 


MEDIA PRESENT 

Returns TRUE if the media is inserted in the device; otherwise, the return is FALSE. 


STATUS (Digital Video Command) Keyword - MODE 


MODE 

Returns not ready, pause, play, record, seek, or stop for the current mode. 


STATUS (Digital Video Command) Keyword - MONITOR 


MONITOR 

Returns ON or OFF. 


STATUS (Digital Video Command) Keyword - MONITOR 
WINDOW HANDLE 


MONITOR WINDOW HANDLE 

Returns the handle of the window used for the monitor window. 


STATUS (Digital Video Command) Keyword - NORMAL 



RATE 


NORMAL RATE 

Returns the normal rate of the currently loaded motion video device element, in the current speed format, either as a percentage or 
frames per second. Otherwise, returns 0. 


STATUS (Digital Video Command) Keyword - NUMBER OF 
TRACKS 


NUMBER OF TRACKS 

Returns the number of tracks on the media. 


STATUS (Digital Video Command) Keyword - PASTE 


PASTE 

Returns TRUE if compatible data is to be placed in clipboard; otherwise, returns FALSE. 


STATUS (Digital Video Command) Keyword - POSITION 


POSITION 

Returns the current position. 


STATUS (Digital Video Command) Keyword - READY 


READY 

Returns TRUE if the digital video device is ready. 


STATUS (Digital Video Command) Keyword - RECORD 
AUDIO 


RECORD AUDIO 



Returns ON or OFF. 


STATUS (Digital Video Command) Keyword - REDO 


REDO 

Returns TRUE if the redo operation can be performed; otherwise, returns FALSE. 


STATUS (Digital Video Command) Keyword - REFERENCE 
FRAME INTERVAL 


REFERENCE FRAME INTERVAL 

Returns the value of n where n refers to a reference frame being inserted every /7th frame. 


STATUS (Digital Video Command) Keyword - 
SAMPLESPERSEC 


SAMPLESPERSEC 

Returns the currently set samples per second used for playing, recording, and saving. 


STATUS (Digital Video Command) Keyword - SATURATION 


SATURATION 

Returns the saturation level. 


STATUS (Digital Video Command) Keyword - SPEED 


SPEED 

Returns the current speed of the device in the currently specified speed format. 


STATUS (Digital Video Command) Keyword - SPEED 



FORMAT 


SPEED FORMAT 

Returns the current speed format of the device. 


STATUS (Digital Video Command) Keyword - TIME FORMAT 


TIME FORMAT 

Returns the time format. 


STATUS (Digital Video Command) Keyword - 
TRANSPARENT COLOR 


TRANSPARENT COLOR 

Returns the value of the transparent color used as the "chroma-key" on video overlay hardware. 


STATUS (Digital Video Command) Keyword - TUNER TV 
CHANNEL 


TUNER TV CHANNEL 

Returns the channel that the tuner device is tuned to. 


STATUS (Digital Video Command) Keyword - TUNER HIGH 
TV CHANNEL 


TUNER HIGH TV CHANNEL 

Returns the highest channel for the region. 


STATUS (Digital Video Command) Keyword - TUNER LOW 
TV CHANNEL 



TUNER LOW TV CHANNEL 

Returns the lowest channel for the region. 


STATUS (Digital Video Command) Keyword - TUNER 
FINETUNE ’ 


TUNER FINETUNE 

Returns the fine-tuning value that the tuner device is tuned to. 


STATUS (Digital Video Command) Keyword - TUNER 
FREQUENCY 


TUNER FREQUENCY 

Returns the frequency value that the tuner device is tuned to. 


STATUS (Digital Video Command) Keyword - UNDO 


UNDO 

Returns TRUE if the undo operation can be performed; otherwise, returns FALSE. 


STATUS (Digital Video Command) Keyword - VALID SIGNAL 


VALID SIGNAL 

Returns TRUE if there is a signal present. 


STATUS (Digital Video Command) Keyword - VERTICAL 
IMAGE EXTENT 


VERTICAL IMAGE EXTENT 

Not supported. 



STATUS (Digital Video Command) Keyword - VERTICAL 
VIDEO EXTENT 


VERTICAL VIDEO EXTENT 

Returns the vertical (Y) extent of the currently loaded motion video. 


STATUS (Digital Video Command) Keyword - VIDEO 
COMPRESSION 


VIDEO COMPRESSION 

Returns the current FOURCC compression type used for recording of motion video. 


STATUS (Digital Video Command) Keyword - VIDEO 
RECORD FRAME DURATION 


VIDEO RECORD FRAME DURATION 

Returns the frame rate for recording as the time duration of each frame in microseconds. 


STATUS (Digital Video Command) Keyword - VIDEO 
RECORD RATE 


VIDEO RECORD RATE 

Returns current rate for recording as an integral number of frames per second. 


STATUS (Digital Video Command) Keyword - VIDEO 
QUALITY 


VIDEO QUALITY 

Returns the motion video quality level. 



STATUS (Digital Video Command) Keyword - VIDEO COLOR 


VIDEO COLOR 

Returns the value of the transparent color used as the "chroma-key" on video overlay hardware. 


STATUS (Digital Video Command) Keyword - VOLUME 


VOLUME 

Returns the current volume setting. The volume is returned as a string in the format /eftr/ght where /eft and right are percentages of 
the maximum achievable effect for the left and right channels respectively. Leading zeros are suppressed for the volume level in each 
channel. 


STATUS (Digital Video Command) Keyword - WINDOW 
HANDLE 


WINDOW HANDLE 

Returns the handle of the window used for the digital video return value. 


STATUS (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


STATUS (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

AUDIOSYNC 

Returns the audio synchronization adjust value. This value is always expressed in MMTIME units. The default value is 0. 

AUDIOSYNC DIRECTION 

Returns the direction of the adjustment in audio synchronization. This is forward of backward relative to video time. The default is 
forward. 

BITSPERSAMPLE 

Returns the currently set bits per sample used for playing, recording, and saving. 

BRIGHTNESS 

Returns the brightness level. 

CHANNELS 

Returns the currently set channel count used for playing, recording, and saving. 

CLIPBOARD 

Returns TRUE if compatible data is in the clipboard; otherwise, returns FALSE. 

CONTRAST 

Returns the contrast level. 

CURRENT TRACK 

Returns the current track. 

DROPPEDFRAMEPCT 

Returns the percentage of dropped frames for playback or recording operations. The value returned is in the range 0-100, where a 
value of 0 indicates that no frame drops are occurring or have occurred. A value of 100 indicates that all frames are being dropped or 
have been dropped. 

This STATUS value can be queried during a recording operation to obtain the cumulative drops that have occurred since recording 
began. This value can also be queried during a playback operation to obtain the cumulative frame drops that have occurred since 
playback began or was resumed after a seek, pause, or stop. If the value is queried when the device is stopped, the percentage of 
dropped frames accumulated at the end of the last playback or recording operation that was performed is returned. 

A value of 0 is returned if no playback or recording operations have been performed, the device is seeking or has been seeked, or the 
device is playing in scan mode. 

GRAPHIC COLOR 

Returns the value of the transparent color used as the "chroma-key" on video overlay hardware. 

HORIZONTAL IMAGE EXTENT 

Not supported. 

HORIZONTAL VIDEO EXTENT 

Returns the horizontal (X) extent of the currently loaded motion video. 


HUE 

Returns the hue level. 

FORMAT TAG 


Returns WAVE_FORMAT_PCM, the only format currently supported by the digital video device. Flowever, if a movie is loaded that 
contains a format other than PCM, the format used in the movie will be returned. 


FORWARD 

Returns TRUE if the play direction is forward or if the device is not playing. 

IMAGE BITSPERPEL 

Returns the number of bits per pel for saving bit maps. 


IMAGE PELFORMAT 

Returns the pel format for saving bit maps or images. 



LENGTH 

Returns the length in the current time format. 

LENGTH TRACK track_number 

Returns the total number of frames in the track specified by track_number. 

MEDIA PRESENT 

Returns TRUE if the media is inserted in the device; otherwise, the return is FALSE. 

MODE 

Returns not ready, pause, play, record, seek, or stop for the current mode. 

MONITOR 

Returns ON or OFF. 

MONITOR WINDOW HANDLE 

Returns the handle of the window used for the monitor window. 

NORMAL RATE 

Returns the normal rate of the currently loaded motion video device element, in the current speed format, either as a percentage or in 
frames per second. Otherwise, returns 0. 

NUMBER OF TRACKS 

Returns the number of tracks on the media. 

PASTE 

Returns TRUE if compatible data is to be placed in clipboard; otherwise, returns FALSE. 

POSITION 

Returns the current position. 

READY 

Returns TRUE if the digital video device is ready. 

RECORD AUDIO 

Returns ON or OFF. 

REDO 

Returns TRUE if the redo operation can be performed; otherwise, returns FALSE. 

REFERENCE FRAME INTERVAL 

Returns the value of n where n refers to a reference frame being inserted every /7th frame. 

SAMPLESPERSEC 

Returns the currently set samples per second used for playing, recording, and saving. 

SATURATION 

Returns the saturation level. 

SPEED 

Returns the current speed of the device in the currently specified speed format. 

SPEED FORMAT 

Returns the current speed format of the device. 

TIME FORMAT 

Returns the time format. 

TRANSPARENT COLOR 

Returns the value of the transparent color used as the "chroma-key" on video overlay hardware. 

TUNER TV CHANNEL 

Returns the channel that the tuner device is tuned to. 

TUNER HIGH TV CHANNEL 

Returns the highest channel for the region. 

TUNER LOW TV CHANNEL 

Returns the lowest channel for the region. 


TUNER FINETUNE 

Returns the fine-tuning value that the tuner device is tuned to. 



TUNER FREQUENCY 

Returns the frequency value that the tuner device is tuned to. 

UNDO 

Returns TRUE if the undo operation can be performed; otherwise, returns FALSE. 

VALID SIGNAL 

Returns TRUE if there is a signal present. 

VERTICAL IMAGE EXTENT 

Not supported. 

VERTICAL VIDEO EXTENT 

Returns the vertical (Y) extent of the currently loaded motion video. 

VIDEO COMPRESSION 

Returns the current FOURCC compression type used for recording of motion video. 

VIDEO RECORD FRAME DURATION 

Returns the frame rate for recording as the time duration of each frame in microseconds. 

VIDEO RECORD RATE 

Returns current rate for recording as an integral number of frames per second. 

VIDEO QUALITY 

Returns the motion video quality level. 

VIDEO COLOR 

Returns the value of the transparent color used as the "chroma-key" on video overlay hardware. 

VOLUME 

Returns the current volume setting. The volume is returned as a string in the format /eft.r/ght where /eft and right are percentages of 
the maximum achievable effect for the left and right channels respectively. Leading zeros are suppressed for the volume level in each 
channel. 

WINDOW HANDLE 

Returns the handle of the window used for the digital video return value. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (Digital Video Command) - Syntax Diagram 
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STEP 


STEP (Digital Video Command) - Example 



step digitalvideo reverse wait 


STEP (Digital Video Command) - Purpose 


The STEP command steps the play one or more frames forward or reverse. The default action is to step one frame forward. 


STEP (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


STEP (Digital Video Command) Keyword - REVERSE 


REVERSE 

Steps the frames in reverse. Only steps to l-frames. 


STEP (Digital Video Command) Keyword - BY frames 


BY frames 

Indicates the number of frames to step. 


STEP (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 



STEP (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STEP (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

REVERSE 

Steps the frames in reverse. Only steps to l-frames. 

BY frames 

Indicates the number of frames to step. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STEP (Digital Video Command) - Syntax Diagram 


STEP object REVERSE 

BY frames 


WAIT 

NOTIFY 


Examples 


STEP (Digital Video Command) - Remarks 


If you are using an application-defined window and your application is running on a system without direct-access device driver support for 
motion video, do not specify WAIT with the STEP command unless the thread issuing the message is separate from the thread reading the 



message queue. 
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UNDO 


UNDO (Digital Video Command) - Example 


open macaw.avi alias vid shareable wait 
delete vid to 8000 wait 
undo digitalvideo wait 


UNDO (Digital Video Command) - Purpose 


The UNDO command undoes the last editing (delete, cut, or paste) change to a file. The position of the media after the undo is 0. Multiple 
UNDO operations are permitted to restore each previously performed editing operation. 


UNDO (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


UNDO (Digital Video Command) Keyword - WAIT 


WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


UNDO (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


UNDO (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


UNDO (Digital Video Command) - Syntax Diagram 


UNDO object 


WAIT 

NOTIFY 


Examples 
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WHERE 


WHERE (Digital Video Command) - Example 


where digitalvideo window monitor wait 


WHERE (Digital Video Command) - Purpose 


The WHERE command obtains a rectangle array specifying the source or destination area. 


WHERE (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


WHERE (Digital Video Command) Keyword - DESTINATION 


DESTINATION 

Requests the position and size of playback video relative to playback window. 


WHERE (Digital Video Command) Keyword - MONITOR 


DESTINATION 


MONITOR DESTINATION 

Requests the position and size of monitor video relative to monitor window. 


WHERE (Digital Video Command) Keyword - RECORD 
DESTINATION 


RECORD DESTINATION 

Requests the size of movie to be recorded. The coordinates returned are those previously set with the PUT object RECORD 
DESTINATION AT rect command. 


WHERE (Digital Video Command) Keyword - ADJUSTED 


ADJUSTED 

Returns the coordinates that will actually be used to record a movie or get an image buffer based on what was previously set with the 
PUT command and the capabilities of the capture hardware. 

An application can use the WHERE command with and without the ADJUSTED keyword to see the effect of the multiple-integral rule 
imposed by capture cards that cannot distort. See PUT for more information on the multiple-integral rule. 


WHERE (Digital Video Command) Keyword - RECORD 
SOURCE 


RECORD SOURCE 

Requests the position and size of source video relative to video source extent. The coordinates returned are those previously set with 

the PUT object RECORD SOURCE AT rect command. 


WHERE (Digital Video Command) Keyword - ADJUSTED 


ADJUSTED 

Returns the coordinates of the source rectangle based on what was previously set with the PUT command and the capabilities of the 
capture hardware. 

An application can use the WHERE command with and without the ADJUSTED keyword to see the effect of the multiple-integral rule 
imposed by capture cards that cannot distort. See PUT for more information on the multiple-integral rule. 


WHERE (Digital Video Command) Keyword - WINDOW 


WINDOW 

Requests the position and size of playback window relative to its parent. 


WHERE (Digital Video Command) Keyword - MONITOR 

MONITOR 

Requests the window size and position for the monitor window. 


WHERE (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


WHERE (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


WHERE (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

DESTINATION 

Requests the position and size of playback video relative to playback window. 

MONITOR DESTINATION 

Requests the position and size of monitor video relative to monitor window. 


RECORD DESTINATION 

Requests the size of movie to be recorded. The coordinates returned are those previously set with the PUT object RECORD 
DESTINATION AT rect command. 


ADJUSTED 

Returns the coordinates that will actually be used to record a movie or get an image buffer based on what was 
previously set with the PUT command o^r/the capabilities of the capture hardware. 


An application can use the WFIERE command with and without the ADJUSTED keyword to see the effect of the 
multiple-integral rule imposed by capture cards that cannot distort. See PUT for more information on the 
multiple-integral rule. 


RECORD SOURCE 

Requests the position and size of source video relative to video source extent. The coordinates returned are those previously set with 

the PUT object RECORD SOURCE AT rect command. 


ADJUSTED 

Returns the coordinates of the source rectangle based on what was previously set with the PUT command anc/Xhe 
capabilities of the capture hardware. 


An application can use the WFIERE command with and without the ADJUSTED keyword to see the effect of the 
multiple-integral rule imposed by capture cards that cannot distort. See PUT for more information on the 
multiple-integral rule. 


WINDOW 

Requests the position and size of playback window relative to its parent. 


MONITOR 

Requests the window size and position for the monitor window. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 

WHERE (Digital Video Command) - Syntax Diagram 

WHERE object DESTINATION 

MONITOR DESTINATION 



RECORD DESTINATION 

ADJUSTED 

RECORD SOURCE 

ADJUSTED 

WINDOW 

MONITOR 


WAIT 

NOTIFY 

Examples 



WHERE (Digital Video Command) - Topics 



Select an item: 

Purpose 

Syntax Diagram 

Keywords 

Example 

Glossary 


WINDOW 


WINDOW (Digital Video Command) - Example 


window digitalvideo handle default wait 


WINDOW (Digital Video Command) - Purpose 


The WINDOW command specifies the window and the window characteristics that a graphic device should use for display. 


WINDOW (Digital Video Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


WINDOW (Digital Video Command) Keyword - HANDLE 
window handle 


HANDLE window handle 

Specifies the handle of the destination window used as an alternate to the default window. 


WINDOW (Digital Video Command) Keyword - HANDLE 
DEFAULT 


HANDLE DEFAULT 

Specifies the digital video driver should create and manage its own window. This flag can be used to set the display back to the 
driver's default window. 


WINDOW (Digital Video Command) Keyword - STATE HIDE 


STATE HIDE 

Hides the current display window. Default window or monitor window only. 


WINDOW (Digital Video Command) Keyword - STATE 
MAXIMIZE 


STATE MAXIMIZE 

Maximizes current display window. Default window or monitor window only. 


WINDOW (Digital Video Command) Keyword - STATE 
MINIMIZE 


STATE MINIMIZE 

Minimizes the specified window and activates the top-level window in the window manager's list. Default window or monitor window 
only. 


WINDOW (Digital Video Command) Keyword - STATE 
MINIMIZED 


STATE MINIMIZED 

Minimizes the current display window. Default window only or monitor window only. 



WINDOW (Digital Video Command) Keyword - STATE 
DEACTIVATE 


STATE DEACTIVATE 

Displays a window in its current state. The window that is currently active remains active. Default window or monitor window only. 


WINDOW (Digital Video Command) Keyword - STATE 
ACTIVATE 


STATE ACTIVATE 

Displays a window in its most recent size and state. The window that is currently active remains active. Default window or monitor 
window only. 


WINDOW (Digital Video Command) Keyword - STATE 
RESTORE 


STATE RESTORE 

Displays the current display window as it was created. Default window or monitor window only. 


WINDOW (Digital Video Command) Keyword - STATE SHOW 


STATE SHOW 

Shows the current display window. Default window or monitor window only. 


WINDOW (Digital Video Command) Keyword - TEXT caption 


TEXT caption 

Specifies the caption for the display window. Default window only. 


WINDOW (Digital Video Command) Keyword - MONITOR 



MONITOR 

Specifies the functions associated with the WINDOW command are to be applied to the monitor window. The monitor window output 
can be directed to an application-specified window in the same manner as video playback. 

Note: This keyword must be last in the string command sequence but precede the WAIT or NOTIFY keywords. 


WINDOW (Digital Video Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


WINDOW (Digital Video Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


WINDOW (Digital Video Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

HANDLE window handle 

Specifies the handle of the destination window used as an alternate to the default window. 

HANDLE DEFAULT 

Specifies the digital video driver should create and manage its own window. This flag can be used to set the display back to the 
driver's default window. 

STATE HIDE 

Hides the current display window. Default window or monitor window only. 

STATE MAXIMIZE 

Maximizes current display window. Default window or monitor window only. 

STATE MINIMIZE 

Minimizes the specified window and activates the top-level window in the window manager's list. Default window or monitor window 
only. 

STATE MINIMIZED 

Minimizes the current display window. Default window only or monitor window only. 


STATE DEACTIVATE 

Displays a window in its current state. The window that is currently active remains active. Default window or monitor window only. 

STATE ACTIVATE 

Displays a window in its most recent size and state. The window that is currently active remains active. Default window or monitor 
window only. 

STATE RESTORE 

Displays the current display window as it was created. Default window or monitor window only. 

STATE SHOW 

Shows the current display window. Default window or monitor window only. 

TEXT caption 

Specifies the caption for the display window. Default window only. 

MONITOR 

Specifies the functions associated with the WINDOW command are to be applied to the monitor window. The monitor window output 
can be directed to an application-specified window in the same manner as video playback. 

Note: This keyword must be last in the string command sequence but precede the WAIT or NOTIFY keywords. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


WINDOW (Digital Video Command) - Syntax Diagram 


WINDOW object 

HANDLE window_handle MONITOR 

HANDLE DEFAULT 

STATE HIDE 

STATE MAXIMIZE 

STATE MINIMIZE 

STATE MINIMIZED 

STATE DEACTIVATE 

STATE ACTIVATE 

STATE RESTORE 

STATE SHOW 

TEXT caption 


WAIT 

NOTIFY 


Examples 
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MIDI Sequencer Commands 


The MIDI sequencer device supports the device-type specific command, CUE, and extensions to the following basic and required 
commands: 


CAPABILITY 

• CLOSE 

• CONNECTOR 

• CUE 

• SET 

• STATUS 


CAPABILITY 


CAPABILITY (MIDI Command) - Example 

The following command returns FALSE. 

capability sequencer can record wait 


CAPABILITY (MIDI Command) - Purpose 


The CAPABILITY command requests additional information about the capabilities of the MIDI sequencer. 


CAPABILITY (MIDI Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


CAPABILITY (MIDI Command) Keyword - CAN EJECT 


CAN EJECT 

Returns FALSE. The sequencer cannot eject the media. 


CAPABILITY (MIDI Command) Keyword - CAN PLAY 


CAN PLAY 

Returns TRUE if the sequencer can play the media. 


CAPABILITY (MIDI Command) Keyword - CAN RECORD 


CAN RECORD 

Returns FALSE. The sequencer cannot record MIDI data. 


CAPABILITY (MIDI Command) Keyword - CAN SAVE 


CAN SAVE 

Returns TRUE if the sequencer can save MIDI data. 


CAPABILITY (MIDI Command) Keyword - CAN SETVOLUME 


CAN SETVOLUME 

Returns TRUE if the device supports software control of volume level. 


CAPABILITY (MIDI Command) Keyword - COMPOUND 
DEVICE 


COMPOUND DEVICE 



Returns TRUE. 


CAPABILITY (MIDI Command) Keyword - DEVICE TYPE 


DEVICE TYPE 

Returns sequencer. 


CAPABILITY (MIDI Command) Keyword - HAS AUDIO 


HAS AUDIO 

Returns TRUE. The sequencer supports playback. 


CAPABILITY (MIDI Command) Keyword - HAS VIDEO 


HAS VIDEO 

Returns FALSE. The sequencer does not support video. 


CAPABILITY (MIDI Command) Keyword - MESSAGE 
command 


MESSAGE command 

Returns TRUE if the device supports the command specified by command. The command can be any string command such as 
OPEN, PLAY, and so on. 


CAPABILITY (MIDI Command) Keyword - PREROLL TIME 


PREROLL TIME 

Returns 0, indicating the preroll time is not bounded. 


CAPABILITY (MIDI Command) Keyword - PREROLL TYPE 



PREROLL TYPE 

Returns the preroll characteristics of the device: Returns NOTIFIED. 


CAPABILITY (MIDI Command) Keyword - USES FILES 

USES FILES 

Returns TRUE. The sequencer uses files for operation. 


CAPABILITY (MIDI Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


CAPABILITY (MIDI Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPABILITY (MIDI Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

CAN EJECT 

Returns FALSE. The sequencer cannot eject the media. 

CAN PLAY 

Returns TRUE if the sequencer can play the media. 

CAN RECORD 

Returns FALSE. The sequencer cannot record MIDI data. 

CAN SAVE 

Returns TRUE if the sequencer can save MIDI data. 


CAN SETVOLUME 

Returns TRUE if the device supports software control of volume level. 

COMPOUND DEVICE 

Returns TRUE. 

DEVICE TYPE 

Returns sequencer. 

HAS AUDIO 

Returns TRUE. The sequencer supports playback. 

HAS VIDEO 

Returns FALSE. The sequencer does not support video. 

MESSAGE command 

Returns TRUE if the device supports the command specified by command. The command can be any string command such as 
OPEN, PLAY, and so on. 

PREROLL TIME 

Returns 0, indicating the preroll time is not bounded. 

PREROLL TYPE 

Returns the preroll characteristics of the device: Returns NOTIFIED. 

USES FILES 

Returns TRUE. The sequencer uses files for operation. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPABILITY (MIDI Command) - Syntax Diagram 


CAPABILITY 


object 


CAN EJECT 
CAN PLAY 
CAN RECORD 
CAN SAVE 
CAN SETVOLUME 
COMPOUND DEVICE 
DEVICE TYPE 
HAS AUDIO 
HAS VIDEO 
MESSAGE command 
PREROLL TYPE 
PREROLL TIME 
USES FILES 


WAIT 

NOTIFY 


Examples 
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CLOSE 


CLOSE (MIDI Command) - Example 

close sequencer wait 


CLOSE (MIDI Command) - Purpose 


The CLOSE command closes the sequencer element and the port and file associated with it. When the last element is closed, MCI unloads 
the sequencer. 


CLOSE (MIDI Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


CLOSE (MIDI Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CLOSE (MIDI Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CLOSE (MIDI Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CLOSE (MIDI Command) - Syntax Diagram 


CLOSE object 

WAIT 

NOTIFY 


Examples 
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CONNECTOR 


CONNECTOR (MIDI Command) - Example 


connector sequencer enable type line out 


CONNECTOR (MIDI Command) - Purpose 


The CONNECTOR command enables, disables, or queries the status of connectors on a device. 


CONNECTOR (MIDI Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CONNECTOR (MIDI Command) Keyword - ENABLE 


ENABLE 

Enables information flow through the indicated connector. Using this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 


CONNECTOR (MIDI Command) Keyword - DISABLE 


DISABLE 



Disables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 


CONNECTOR (MIDI Command) Keyword - QUERY 


QUERY 

Queries the status of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled 
respectively. Using this option requires that the NUMBER or TYPE keywords, or both also be specified. 


CONNECTOR (MIDI Command) Keyword - NUMBER 
connector number 


NUMBER connector number 

The connector number on which to perform the requested action. If the TYPE keyword is included, the connector number is 
interpreted as a relative offset within the specified connector type. 


CONNECTOR (MIDI Command) Keyword - TYPE 
connector_type 


TYPE connector type 

Indicates the type of connector to which the requested action applies. The following connector types are directly supported by this 
device: 

MIDI stream 

Digital input or output for the audio amplifier/mixer. This connector is always enabled. 

The MIDI sequencer device also recognizes the following connector types and will attempt to control the corresponding amp/mixer 
connector if the amp/mixer provides the support. 

line out 

The line output connector. This connector is usually attached to the line in connector of another device such as a 
tape recorder or other audio device. 

speakers 

The speakers connector. This connector is usually attached to a pair of external or internal speakers. 

headphones 

The headphones connector. This connector is usually attached to a pair of headphones. 


CONNECTOR (MIDI Command) Keyword - WAIT 



WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CONNECTOR (MIDI Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTOR (MIDI Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

ENABLE 

Enables information flow through the indicated connector. Using this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 

DISABLE 

Disables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 

QUERY 

Queries the status of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled 
respectively. Using this option requires that the NUMBER or TYPE keywords, or both also be specified. 

NUMBER connectornumber 

The connector number on which to perform the requested action. If the TYPE keyword is included, the connector number is 
interpreted as a relative offset within the specified connector type. 

TYPE connector type 

Indicates the type of connector to which the requested action applies. The following connector types are directly supported by this 
device: 

MIDI stream 

Digital input or output for the audio amplifier/mixer. This connector is always enabled. 

The MIDI sequencer device also recognizes the following connector types and will attempt to control the corresponding amp/mixer 
connector if the amp/mixer provides the support. 

line out 

The line output connector. This connector is usually attached to the line in connector of another device such as a 
tape recorder or other audio device. 

speakers 

The speakers connector. This connector is usually attached to a pair of external or internal speakers. 

headphones 

The headphones connector. This connector is usually attached to a pair of headphones. 


WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 


application. 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTOR (MIDI Command) - Syntax Diagram 


CONNECTOR object ENABLE 

DISABLE 

QUERY 


NUMBER connector_number 

TYPE connector_type WAIT 

NOTIFY 


Examples 
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CUE 


CUE (MIDI Command) - Example 


open sequencerOl alias seq wait 
load seq sounds. mid wait 
cue seq output wait 



CUE (MIDI Command) - Purpose 


The CUE command prepares for playback or recording. The CUE command does not have to be issued prior to playback or recording; 
however, depending on the device, it might reduce the delay associated with the PLAY or RECORD command. The command fails if playing 
or recording is in progress. 

The CUE command is not related to the SETCUEPOINT command. 


CUE (MIDI Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


CUE (MIDI Command) Keyword - INPUT 


INPUT 

Prepares the device for recording. 


CUE (MIDI Command) Keyword - OUTPUT 


OUTPUT 

Prepares the device for playback. 


CUE (MIDI Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CUE (MIDI Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CUE (MIDI Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


INPUT 

Prepares the device for recording. 

OUTPUT 

Prepares the device for playback. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CUE (MIDI Command) - Syntax Diagram 


CUE object 


INPUT 

OUTPUT 


WAIT 

NOTIFY 


Examples 
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SET 


SET (MIDI Command) - Example 


set sequencer time format ms wait 


SET (MIDI Command) - Purpose 


The SET command sets the various control items. 


SET (MIDI Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


SET (MIDI Command) Keyword - AUDIO 


AUDIO 

Sets the audio attributes of the device context specified by the ALL, LEFT, RIGHT, OVER and VOLUME keywords. 


SET (MIDI Command) Keyword - ALL 


ALL 


Applies to both or all of the channels (default). 
Specify ON or OFF with the ALL keyword. 


SET (MIDI Command) Keyword - ON 


ON 

Enables audio output. 


SET (MIDI Command) Keyword - OFF 


OFF 

Disables audio output. 


SET (MIDI Command) Keyword - LEFT 


LEFT 

Applies to left channel. 

Specify ON or OFF with the LEFT keyword. 


SET (MIDI Command) Keyword - ON 


ON 

Enables audio output to the left channel. 


SET (MIDI Command) Keyword - OFF 


OFF 

Disables audio output to the left channel. 


SET (MIDI Command) Keyword - RIGHT 



RIGHT 

Applies to right channel. 

Specify ON or OFF with the RIGFIT keyword. 


SET (MIDI Command) Keyword - ON 


ON 

Enables audio output to the right channel. 


SET (MIDI Command) Keyword - OFF 


OFF 

Disables audio output to the right channel. 


SET (MIDI Command) Keyword - OVER milliseconds 


OVER milliseconds 

Applies the change over the specified time period (fade). 


SET (MIDI Command) Keyword - VOLUME percentage 


VOLUME percentage 

Sets the device/mixer channel volume level. 


SET (MIDI Command) Keyword - MASTER MIDI 


MASTER MIDI 

Sets the MIDI sequencer as the synchronization source. Synchronization data is sent in MIDI format. The IBM sequencer does not 
support this option. 



SET (MIDI Command) Keyword - MASTER NONE 


MASTER NONE 

Inhibits the sequencer from sending synchronization data. The IBM sequencer does not support this option. 


SET (MIDI Command) Keyword - MASTER SMPTE 


MASTER SMPTE 

Sets the MIDI sequencer as the synchronization source. Synchronization data is sent in SMPTE format. The IBM sequencer does not 
support this option. 


SET (MIDI Command) Keyword - OFFSET time 


OFFSET time 

The SMPTE offset time in colon form (HOURS:MINUTES:SECONDS:FRAMES). 


SET (MIDI Command) Keyword - PORT MAPPER 


PORT MAPPER 

The MIDI mapper is the port receiving the MIDI messages. This command will fail if the MIDI mapper or a port it needs is being used 
by another sequence or client. 


SET (MIDI Command) Keyword - PORT NONE 


PORT NONE 

Disables the sending of MIDI messages. Currently this function is not supported by the IBM sequencer. 


SET (MIDI Command) Keyword - SLAVE FILE 


SLAVE FILE 

Sets the MIDI sequencer to use file data as the synchronization source. This is the default. 



SET (MIDI Command) Keyword - SLAVE MIDI 


SLAVE MIDI 

Sets the MIDI sequencer to use incoming MIDI data as the synchronization source. The sequencer recognizes synchronization data 
with the MIDI format. The IBM sequencer does not support this option. 


SET (MIDI Command) Keyword - SLAVE NONE 


SLAVE NONE 

Sets the MIDI sequencer to ignore synchronization data. 


SET (MIDI Command) Keyword - SLAVE SMPTE 


SLAVE SMPTE 

Sets the MIDI sequencer to use incoming MIDI data for the synchronization source. The sequencer recognizes synchronization data 
with the SMPTE format. The IBM sequencer does not support this option. 


SET (MIDI Command) Keyword - TEMPO integer 


TEMPO integer 

The tempo of the sequence according to the current time format. For a ppqn-based file, the integer is interpreted as beats per 
minute. For a SMPTE based file, the integer is interpreted as frames per second. 


SET (MIDI Command) Keyword - TIME FORMAT 
MILLISECONDS 


TIME FORMAT MILLISECONDS 

Sets time format to milliseconds. All position information is specified as milliseconds following this command. The sequence file sets 
the default format to ppqn or SMPTE. You can abbreviate milliseconds as ms. 


SET (MIDI Command) Keyword - TIME FORMAT MMTIME 



TIME FORMAT MMTIME 

Sets the time format to MMTIME. 


SET (MIDI Command) Keyword - TIME FORMAT SONG 
POINTER 


TIME FORMAT SONG POINTER 

Sets the time format to song-pointer (sixteenth notes). This can only be performed for a sequence of division type ppqn. Currently this 
function is not supported by the IBM sequencer. 


SET (MIDI Command) Keyword - TIME FORMAT SMPTE 24 


TIME FORMAT SMPTE 24 

Sets the time format to SMPTE 24 frame rate. All position information is specified in SMPTE format following this command. The 
sequence file sets the default format to ppqn or SMPTE. 


SET (MIDI Command) Keyword - TIME FORMAT SMPTE 25 


TIME FORMAT SMPTE 25 

Sets the time format to SMPTE 25 frame rate. All position information is specified in SMPTE format following this command. The 
sequence file sets the default format to ppqn or SMPTE. 


SET (MIDI Command) Keyword - TIME FORMAT SMPTE 30 


TIME FORMAT SMPTE 30 

Sets the time format to SMPTE 30 frame rate. All position information is specified in SMPTE format following this command. The 
sequence file sets the default format to ppqn or SMPTE. 


SET (MIDI Command) Keyword - TIME FORMAT SMPTE 30 
DROP 



TIME FORMAT SMPTE 30 DROP 

Sets the time format to SMPTE 30 drop frame rate. All position information is specified in SMPTE format following this command. The 
sequence file sets the default format to ppqn or SMPTE. Currently this function is not supported by the IBM sequencer. 


SET (MIDI Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SET (MIDI Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


SET (MIDI Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

AUDIO 

Sets the audio attributes of the device context specified by the ALL, LEFT, RIGHT, OVER and VOLUME keywords. 

ALL 

Applies to both or all of the channels (default). 

Specify ON or OFF with the ALL keyword. 

ON 

Enables audio output. 

OFF 

Disables audio output. 

LEFT 

Applies to left channel. 

Specify ON or OFF with the LEFT keyword. 

ON 

Enables audio output to the left channel. 

OFF 

Disables audio output to the left channel. 


RIGHT 


Applies to right channel. 

Specify ON or OFF with the FtIGFIT keyword. 

ON 

Enables audio output to the right channel. 


OFF 


Disables audio output to the right channel. 


OVER milliseconds 

Applies the change over the specified time period (fade). 

VOLUME percentage 

Sets the device/mixer channel volume level. 


MASTER MIDI 

Sets the MIDI sequencer as the synchronization source. Synchronization data is sent in MIDI format. The IBM sequencer does not 
support this option. 

MASTER NONE 

Inhibits the sequencer from sending synchronization data. The IBM sequencer does not support this option. 

MASTER SMPTE 

Sets the MIDI sequencer as the synchronization source. Synchronization data is sent in SMPTE format. The IBM sequencer does not 
support this option. 

OFFSET time 

The SMPTE offset time in colon form (HOURS:MINUTES:SECONDS:FRAMES). 

PORT MAPPER 

The MIDI mapper is the port receiving the MIDI messages. This command will fail if the MIDI mapper or a port it needs is being used 
by another sequence or client. 

PORT NONE 

Disables the sending of MIDI messages. Currently this function is not supported by the IBM sequencer. 

SLAVE FILE 

Sets the MIDI sequencer to use file data as the synchronization source. This is the default. 

SLAVE MIDI 

Sets the MIDI sequencer to use incoming MIDI data as the synchronization source. The sequencer recognizes synchronization data 
with the MIDI format. The IBM sequencer does not support this option. 

SLAVE NONE 

Sets the MIDI sequencer to ignore synchronization data. 


SLAVE SMPTE 

Sets the MIDI sequencer to use incoming MIDI data for the synchronization source. The sequencer recognizes synchronization data 
with the SMPTE format. The IBM sequencer does not support this option. 

TEMPO integer 

The tempo of the sequence according to the current time format. For a ppqn-based file, the integer is interpreted as beats per 
minute. For a SMPTE based file, the integer is interpreted as frames per second. 

TIME FORMAT MILLISECONDS 

Sets time format to milliseconds. All position information is specified as milliseconds following this command. The sequence file sets 
the default format to ppqn or SMPTE. You can abbreviate milliseconds as ms. 

TIME FORMAT MMTIME 

Sets the time format to MMTIME. 

TIME FORMAT SONG POINTER 

Sets the time format to song-pointer (sixteenth notes). This can only be performed for a sequence of division type ppqn. Currently this 
function is not supported by the IBM sequencer. 

TIME FORMAT SMPTE 24 

Sets the time format to SMPTE 24 frame rate. All position information is specified in SMPTE format following this command. The 
sequence file sets the default format to ppqn or SMPTE. 


TIME FORMAT SMPTE 25 

Sets the time format to SMPTE 25 frame rate. All position information is specified in SMPTE format following this command. The 



sequence file sets the default format to ppqn or SMPTE. 

TIME FORMAT SMPTE 30 

Sets the time format to SMPTE 30 frame rate. All position information is specified in SMPTE format following this command. The 
sequence file sets the default format to ppqn or SMPTE. 

TIME FORMAT SMPTE 30 DROP 

Sets the time format to SMPTE 30 drop frame rate. All position information is specified in SMPTE format following this command. The 
sequence file sets the default format to ppqn or SMPTE. Currently this function is not supported by the IBM sequencer. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


SET (MIDI Command) - Syntax Diagram 
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STATUS 


STATUS (MIDI Command) - Example 


status sequencer ready wait 


STATUS (MIDI Command) - Purpose 


The STATUS command obtains status information for the MIDI sequencer. 


STATUS (MIDI Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


STATUS (MIDI Command) Keyword - CURRENT TRACK 


CURRENT TRACK 

Returns the current track number. 


STATUS (MIDI Command) Keyword - DIVISION TYPE 


DIVISION TYPE 

Returns the file division type. This can be one of: PPQN, SMPTE 24 frame, SMPTE 25 frame, SMPTE 30 frame, or SMPTE 30 drop 
frame. Use this information to determine the format of the MIDI file, and the meaning of tempo and position information. 


STATUS (MIDI Command) Keyword - LENGTH 


LENGTH 

Returns the length of a sequence in the current time format. For ppqn files, this will be song pointer units. Plowever, for SMPTE files, 
this will be in colon form (HOURS:MINUTES:SECONDS:FRAMES). 


STATUS (MIDI Command) Keyword - LENGTH TRACK 
number 


LENGTH TRACK number 

Returns the length of a track in the current time format. For ppqn files, this will be song pointer units. Plowever, for SMPTE files, this 
will be in colon form (HOURS:MINUTES:SECONDS:FRAMES). 


STATUS (MIDI Command) Keyword - MASTER 

MASTER 

Returns midi, none, or smpte, depending on the type of synchronization set. 


STATUS (MIDI Command) Keyword - MEDIA PRESENT 

MEDIA PRESENT 

The sequencer returns TRUE. 


STATUS (MIDI Command) Keyword - MODE 


MODE 


Returns the current mode of the device: not ready, stopped, playing, seeking, recording, paused, or other. 



STATUS (MIDI Command) Keyword - NUMBER OF TRACKS 


NUMBER OF TRACKS 

Returns the number of tracks. 


STATUS (MIDI Command) Keyword - OFFSET 


OFFSET 

Returns the offset of a SMPTE-based file. The offset is the beginning time of a SMPTE-based sequence. The MIDI sequencer driver 
returns the time in colon form (HOURS:MINUTES:SECONDS:FRAMES). 


STATUS (MIDI Command) Keyword - PORT 


PORT 

Returns the MIDI port number assigned to the sequence. Currently this function is not supported by the IBM sequencer. 


STATUS (MIDI Command) Keyword - POSITION 


POSITION 

Returns the current position of a sequence in the current time format. For ppqn files, this will be song pointer units. Flowever, for 
SMPTE files, this will be in colon form (FIOURS:MINUTES:SECONDS:FRAMES). Currently this function is not supported by the IBM 
sequencer. 


STATUS (MIDI Command) Keyword - POSITION TRACK 
number 


POSITION TRACK number 

Returns the current position of the track specified by number in the current time format. For ppqn files, this will be song pointer units. 
However, for SMPTE files, this will be in colon form (HOURS:MINUTES:SECONDS:FRAMES). 


STATUS (MIDI Command) Keyword - READY 



READY 

Returns TRUE if the device is ready. 


STATUS (MIDI Command) Keyword - SLAVE 


SLAVE 

Returns file, midi, none, or smpte depending on the type of synchronization set. 


STATUS (MIDI Command) Keyword - START POSITION 


START POSITION 

Returns the starting position of the media or device element. 


STATUS (MIDI Command) Keyword - TEMPO 


TEMPO 

Returns the current tempo of a sequence in the current time format. For files with ppqn format, the tempo is in beats-per-minute. For 
files with SMPTE format, the tempo is in frames-per-second. 


STATUS (MIDI Command) Keyword - TIME FORMAT 


TIME FORMAT 

Returns the time format. 


STATUS (MIDI Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 



STATUS (MIDI Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CURRENT TRACK 

Returns the current track number. 

DIVISION TYPE 

Returns the file division type. This can be one of: PPQN, SMPTE 24 frame, SMPTE 25 frame, SMPTE 30 frame, or SMPTE 30 drop 
frame. Use this information to determine the format of the MIDI file, and the meaning of tempo and position information. 

LENGTH 

Returns the length of a sequence in the current time format. For ppqn files, this will be song pointer units. Flowever, for SMPTE files, 
this will be in colon form (HOURS:MINUTES:SECONDS:FRAMES). 

LENGTH TRACK number 

Returns the length of a track in the current time format. For ppqn files, this will be song pointer units. Flowever, for SMPTE files, this 
will be in colon form (HOURS:MINUTES:SECONDS:FRAMES). 

MASTER 

Returns midi, none, or smpte, depending on the type of synchronization set. 

MEDIA PRESENT 

The sequencer returns TRUE. 

MODE 

Returns the current mode of the device: not ready, stopped, playing, seeking, recording, paused, or other. 

NUMBER OF TRACKS 

Returns the number of tracks. 

OFFSET 

Returns the offset of a SMPTE-based file. The offset is the beginning time of a SMPTE-based sequence. The MIDI sequencer driver 
returns the time in colon form (HOURS:MINUTES:SECONDS:FRAMES). 

PORT 

Returns the MIDI port number assigned to the sequence. Currently this function is not supported by the IBM sequencer. 

POSITION 

Returns the current position of a sequence in the current time format. For ppqn files, this will be song pointer units. However, for 
SMPTE files, this will be in colon form (HOURS:MINUTES:SECONDS:FRAMES). Currently this function is not supported by the IBM 
sequencer. 

POSITION TRACK number 

Returns the current position of the track specified by number in the current time format. For ppqn files, this will be song pointer units. 
However, for SMPTE files, this will be in colon form (HOURS:MINUTES:SECONDS:FRAMES). 

READY 

Returns TRUE if the device is ready. 



object 


Object associated with this media control interface command. The object can be one of the following: 


Device type 
Device name 
Filename 
Alias 


SLAVE 

Returns file, midi, none, or smpte depending on the type of synchronization set. 

START POSITION 

Returns the starting position of the media or device element. 

TEMPO 

Returns the current tempo of a sequence in the current time format. For files with ppqn format, the tempo is in beats-per-minute. For 
files with SMPTE format, the tempo is in frames-per-second. 

TIME FORMAT 

Returns the time format. 

WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


STATUS (MIDI Command) - Syntax Diagram 
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Videodisc Player Commands 


The videodisc device supports the following device-type specific commands and extensions to the following basic and required commands: 

CAPABILITY 

• CONNECTOR 
CUE 

• ESCAPE 
INFO 

• PAUSE 
PLAY 

• SEEK 
SET 

• SPIN 

• STATUS 

• STEP 


CAPABILITY 


CAPABILITY (Videodisc Player Command) - Example 


The following command returns FALSE. 

capability videodisc can record wait 


CAPABILITY (Videodisc Player Command) - Purpose 

The CAPABILITY command requests additional information about the capabilities of the device. 


CAPABILITY (Videodisc Player Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


CAPABILITY (Videodisc Player Command) Keyword - CAN 
EJECT 


CAN EJECT 

Returns TRUE if the device can eject the media. 


CAPABILITY (Videodisc Player Command) Keyword - CAN 
PLAY 


CAN PLAY 

Returns TRUE. 


CAPABILITY (Videodisc Player Command) Keyword - CAN 
RECORD 


CAN RECORD 

Returns FALSE. The device cannot record. 


CAPABILITY (Videodisc Player Command) Keyword - CAN 
REVERSE 


CAN REVERSE 

Returns TRUE if the device can play in reverse. 


CAPABILITY (Videodisc Player Command) Keyword - CAN 
SAVE 


CAN SAVE 

Returns FALSE. Videodisc players cannot save data. 



CAPABILITY (Videodisc Player Command) Keyword - CAN 
SETVOLUME 


CAN SETVOLUME 

Returns TRUE if the device supports software control of volume level. 


CAPABILITY (Videodisc Player Command) Keyword - CAV 


CAV 

When combined with other items, CAV specifies that the returned information applies to CAV formatted discs. This is the default. 


CAPABILITY (Videodisc Player Command) Keyword - CLV 


CLV 

When combined with other items, CLV specifies that the returned information applies to CLV formatted discs. 


CAPABILITY (Videodisc Player Command) Keyword - 
COMPOUND DEVICE 


COMPOUND DEVICE 

Returns FALSE. Videodisc players are simple devices. 


CAPABILITY (Videodisc Player Command) Keyword - 
DEVICE TYPE 


DEVICE TYPE 

Returns Videodisc. 


CAPABILITY (Videodisc Player Command) Keyword - FAST 



PLAY RATE 


FAST PLAY RATE 

Returns the fast play rate in the current speed format, either as a percentage or in frames per second. Returns 0 if the device cannot 
play fast. 


CAPABILITY (Videodisc Player Command) Keyword - HAS 
AUDIO 


HAS AUDIO 

Returns TRUE if the video device has audio. 


CAPABILITY (Videodisc Player Command) Keyword - HAS 
VIDEO 


HAS VIDEO 

Returns TRUE. 


CAPABILITY (Videodisc Player Command) Keyword - 
MAXIMUM PLAY RATE 


MAXIMUM PLAY RATE 

Returns the maximum play rate in the current speed format, either as a percentage or in frames per second. 


CAPABILITY (Videodisc Player Command) Keyword - 
MESSAGE command 


MESSAGE command 

Returns TRUE if the device supports the command specified by command. The command can be any string command such as 
OPEN, PLAY, and so on. 


CAPABILITY (Videodisc Player Command) Keyword - 



MINIMUM PLAY RATE 


MINIMUM PLAY RATE 

Returns the minimum play rate in the current speed format, either as a percentage or in frames per second. 


CAPABILITY (Videodisc Player Command) Keyword - 
NORMAL PLAY RATE 


NORMAL PLAY RATE 

Returns the normal rate of play in frames per second. 


CAPABILITY (Videodisc Player Command) Keyword - 
PREROLL TIME 


PREROLL TIME 

Returns 0, indicating the preroll time is not bounded. 


CAPABILITY (Videodisc Player Command) Keyword - 
PREROLL TYPE 


PREROLL TYPE 

Returns NOTIFIED. 


CAPABILITY (Videodisc Player Command) Keyword - SLOW 
PLAY RATE 


SLOW PLAY RATE 

Returns the slow play rate in the current speed format, either as a percentage or in frames per second. Returns 0 if the device cannot 
play slow. 


CAPABILITY (Videodisc Player Command) Keyword - USES 



FILES 


USES FILES 

Returns FALSE. Videodisc players do not use files. 


CAPABILITY (Videodisc Player Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


CAPABILITY (Videodisc Player Command) Keyword - 
NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPABILITY (Videodisc Player Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

CAN EJECT 

Returns TRUE if the device can eject the media. 

CAN PLAY 

Returns TRUE. 

CAN RECORD 

Returns FALSE. The device cannot record. 

CAN REVERSE 

Returns TRUE if the device can play in reverse. 

CAN SAVE 

Returns FALSE. Videodisc players cannot save data. 

CAN SETVOLUME 

Returns TRUE if the device supports software control of volume level. 


CAV 


When combined with other items, CAV specifies that the returned information applies to CAV formatted discs. This is the default. 

CLV 

When combined with other items, CLV specifies that the returned information applies to CLV formatted discs. 

COMPOUND DEVICE 

Returns FALSE. Videodisc players are simple devices. 

DEVICE TYPE 

Returns Videodisc. 

FAST PLAY RATE 

Returns the fast play rate in the current speed format, either as a percentage or in frames per second. Returns 0 if the device cannot 
play fast. 

HAS AUDIO 

Returns TRUE if the video device has audio. 

HAS VIDEO 

Returns TRUE. 

MAXIMUM PLAY RATE 

Returns the maximum play rate in the current speed format, either as a percentage or in frames per second. 

MESSAGE command 

Returns TRUE if the device supports the command specified by command. The command can be any string command such as 
OPEN, PLAY, and so on. 

MINIMUM PLAY RATE 

Returns the minimum play rate in the current speed format, either as a percentage or in frames per second. 

NORMAL PLAY RATE 

Returns the normal rate of play in frames per second. 

PREROLL TIME 

Returns 0, indicating the preroll time is not bounded. 

PREROLL TYPE 

Returns NOTIFIED. 

SLOW PLAY RATE 

Returns the slow play rate in the current speed format, either as a percentage or in frames per second. Returns 0 if the device cannot 
play slow. 

USES FILES 

Returns FALSE. Videodisc players do not use files. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPABILITY (Videodisc Player Command) - Syntax Diagram 
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CONNECTOR 


CONNECTOR (Videodisc Player Command) - Example 


connector videodisc enable type line out 


CONNECTOR (Videodisc Player Command) - Purpose 


The CONNECTOR command enables, disables, or queries the status of connectors on a device. 


CONNECTOR (Videodisc Player Command) Keyword - object 



object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CONNECTOR (Videodisc Player Command) Keyword - 
ENABLE 


ENABLE 

Enables information flow through the indicated connector. Using this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 


CONNECTOR (Videodisc Player Command) Keyword - 
DISABLE 


DISABLE 

Disables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 


CONNECTOR (Videodisc Player Command) Keyword - 
QUERY 


QUERY 

Queries the status of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled 
respectively. Using this option requires that the NUMBER or TYPE keywords, or both also be specified. 


CONNECTOR (Videodisc Player Command) Keyword - 
NUMBER connector number 


NUMBER connector number 

The connector number on which to perform the requested action. If the TYPE keyword is included, the connector number is 
interpreted as a relative offset within the specified connector type. 



CONNECTOR (Videodisc Player Command) Keyword - TYPE 
connector_type 


TYPE connectortype 

Indicates the type of connector to which the requested action applies. The following connector types are directly supported by this 
device: 

line out 

The line output connector. This connector is usually attached to the line in connector of another device such as a 
set of amplified speakers or other audio devices. 

video out 

The video output connector. This connector is usually attached to the video input of an external monitor or a 
video overlay board. 


CONNECTOR (Videodisc Player Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CONNECTOR (Videodisc Player Command) Keyword - 
NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTOR (Videodisc Player Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

ENABLE 

Enables information flow through the indicated connector. Using this option requires that the NUMBER or TYPE keywords, or both 
also be specified. 

DISABLE 

Disables information flow through the indicated connector. Use of this option requires that the NUMBER or TYPE keywords, or both 


also be specified. 


QUERY 

Queries the status of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled 
respectively. Using this option requires that the NUMBER or TYPE keywords, or both also be specified. 

NUMBER connectornumber 

The connector number on which to perform the requested action. If the TYPE keyword is included, the connector number is 
interpreted as a relative offset within the specified connector type. 

TYPE connector type 

Indicates the type of connector to which the requested action applies. The following connector types are directly supported by this 
device: 

line out 

The line output connector. This connector is usually attached to the line in connector of another device such as a 
set of amplified speakers or other audio devices. 

video out 

The video output connector. This connector is usually attached to the video input of an external monitor or a 
video overlay board. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


CONNECTOR (Videodisc Player Command) - Syntax 
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CUE 


CUE (Videodisc Player Command) - Example 

cue videodisc input wait 


CUE (Videodisc Player Command) - Purpose 


The CUE command prepares for playback or recording. The CUE command does not have to be issued prior to playback or recording; 
however, depending on the device, it might reduce the delay associated with the PLAY or RECORD command. The command fails if playing 
or recording is in progress. 

The CUE command is not related to the SETCUEPOINT command. 


CUE (Videodisc Player Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CUE (Videodisc Player Command) Keyword - INPUT 


INPUT 

Prepares the device for recording. 


CUE (Videodisc Player Command) Keyword - OUTPUT 


OUTPUT 

Prepares the device for playback. This is the default. 


CUE (Videodisc Player Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CUE (Videodisc Player Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CUE (Videodisc Player Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


INPUT 

Prepares the device for recording. 

OUTPUT 

Prepares the device for playback. This is the default. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CUE (Videodisc Player Command) - Syntax Diagram 
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ESCAPE 


ESCAPE (Videodisc Player Command) - Example 


escape videodisc ?? wait 


ESCAPE (Videodisc Player Command) - Purpose 


The ESCAPE command sends custom information to a device. 


ESCAPE (Videodisc Player Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 



Alias 


ESCAPE (Videodisc Player Command) Keyword - string 


string 

The custom information sent to the device. 


ESCAPE (Videodisc Player Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


ESCAPE (Videodisc Player Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


ESCAPE (Videodisc Player Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


string 

The custom information sent to the device. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


ESCAPE (Videodisc Player Command) - Syntax Diagram 
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Examples 
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INFO 


INFO (Videodisc Player Command) - Example 


info videodisc product wait 


INFO (Videodisc Player Command) - Purpose 


The INFO command fills a user-supplied buffer with information. 


INFO (Videodisc Player Command) Keyword - object 


object 


Object associated with this media control interface command. The object can be one of the following: 



Device type 
Device name 
Filename 
Alias 


INFO (Videodisc Player Command) Keyword - PRODUCT 

PRODUCT 

Returns the product name of the device the peripheral is controlling. 


INFO (Videodisc Player Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


INFO (Videodisc Player Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


INFO (Videodisc Player Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 

PRODUCT 

Returns the product name of the device the peripheral is controlling. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


INFO (Videodisc Player Command) - Syntax Diagram 


INFO object PRODUCT 


WAIT 

NOTIFY 


Examples 
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PAUSE 


PAUSE (Videodisc Player Command) - Example 


pause videodisc wait 


PAUSE (Videodisc Player Command) - Purpose 


The PAUSE command pauses playing. For CAV discs, it also freezes the video frame. 


PAUSE (Videodisc Player Command) Keyword - object 



object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


PAUSE (Videodisc Player Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


PAUSE (Videodisc Player Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


PAUSE (Videodisc Player Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


PAUSE (Videodisc Player Command) - Syntax Diagram 


PAUSE 


object 


WAIT 

NOTIFY 


Examples 


PAUSE (Videodisc Player Command) - Topics 
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PLAY 


PLAY (Videodisc Player Command) - Example 


play videodisc fast notify 


PLAY (Videodisc Player Command) - Purpose 


The PLAY command starts playing. 


PLAY (Videodisc Player Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 



PLAY (Videodisc Player Command) Keyword - FROM pos 


FROM pos 

Specifies the frame at which to start playing. If FROM is omitted, PLAY starts at the current position. 


PLAY (Videodisc Player Command) Keyword - TO pos 


TO pos 

Specifies the frame at which to stop playing. If TO is omitted, PLAY stops at the end frame. 


PLAY (Videodisc Player Command) Keyword - FAST 


FAST 

The device is to play faster than normal. To specify the speed more precisely, use the SPEED keyword. To determine the exact 
speed of a particular player, use the STATUS object SPEED command. 


PLAY (Videodisc Player Command) Keyword - REVERSE 


REVERSE 

The play direction is backwards. This applies only to CAV discs. 


PLAY (Videodisc Player Command) Keyword - SLOW 


SLOW 

The device is to play slower than normal. 


PLAY (Videodisc Player Command) Keyword - SCAN 


SCAN 


The play speed is as fast as possible, possibly with audio disabled. This applies only to CAV discs. 


PLAY (Videodisc Player Command) Keyword - SPEED units 

SPEED units 

Play at the specified speed. Speed is set in units specified by SET object SPEED FORMAT. This applies only to CAV discs. 


PLAY (Videodisc Player Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


PLAY (Videodisc Player Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


PLAY (Videodisc Player Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

FROM pos 

Specifies the frame at which to start playing. If FROM is omitted, PLAY starts at the current position. 

TO pos 

Specifies the frame at which to stop playing. If TO is omitted, PLAY stops at the end frame. 


FAST 

The device is to play faster than normal. To specify the speed more precisely, use the SPEED keyword. To determine the exact 
speed of a particular player, use the STATUS object SPEED command. 


REVERSE 

The play direction is backwards. This applies only to CAV discs. 


SLOW 


The device is to play slower than normal. 


SCAN 

The play speed is as fast as possible, possibly with audio disabled. This applies only to CAV discs. 

SPEED units 

Play at the specified speed. Speed is set in units specified by SET object SPEED FORMAT. This applies only to CAV discs. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


PLAY (Videodisc Player Command) - Syntax Diagram 


PLAY object 


FROM pos 
TO pos 


FAST 

REVERSE 

SCAN 

SLOW 

SPEED units 


WAIT 

NOTIFY 


Examples 
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SEEK 



SEEK (Videodisc Player Command) - Example 


seek videodiscOl to start wait 


SEEK (Videodisc Player Command) - Purpose 


The SEEK command searches, using fast forward or fast reverse, with video and audio off. 


SEEK (Videodisc Player Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


SEEK (Videodisc Player Command) Keyword - REVERSE 


REVERSE 

The seek direction on CAV discs is backwards. This modifier is invalid if TO is specified. 


SEEK (Videodisc Player Command) Keyword - TO pos 


TO pos 

Specifies the final position to stop the seek. If TO is not specified, the seek continues until the end of the media is reached. 


SEEK (Videodisc Player Command) Keyword - TO START 


TO START 

Seeks to the start of the disc. 



SEEK (Videodisc Player Command) Keyword - TO END 


TO END 

Seeks to the end of the disc. 


SEEK (Videodisc Player Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SEEK (Videodisc Player Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


SEEK (Videodisc Player Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 

REVERSE 

The seek direction on CAV discs is backwards. This modifier is invalid if TO is specified. 

TO pos 

Specifies the final position to stop the seek. If TO is not specified, the seek continues until the end of the media is reached. 

TO START 

Seeks to the start of the disc. 

TO END 

Seeks to the end of the disc. 


WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SEEK (Videodisc Player Command) - Syntax Diagram 


SEEK object REVERSE 

TO pos 
TO START 
TO END 


WAIT 

NOTIFY 


Examples 
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SET 


SET (Videodisc Player Command) - Example 


set videodisc time format milliseconds wait 


SET (Videodisc Player Command) - Purpose 


The SET command sets the various control and attribute items. 



SET (Videodisc Player Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


SET (Videodisc Player Command) Keyword - AUDIO 


AUDIO 

Specifies the audio attributes of the device context determined by the ALL, LEFT, and RIGFIT keywords. 


SET (Videodisc Player Command) Keyword - ALL 


ALL 

Applies to both or all of the channels (default). 
Specify ON or OFF with the ALL keyword. 


SET (Videodisc Player Command) Keyword - ON 


ON 

Enables audio. 


SET (Videodisc Player Command) Keyword - OFF 


OFF 

Disables audio. 


SET (Videodisc Player Command) Keyword - LEFT 



LEFT 


Applies to the left channel. 

Specify ON or OFF with the LEFT keyword. 


SET (Videodisc Player Command) Keyword - ON 


ON 

Enables output to the left audio channel. 


SET (Videodisc Player Command) Keyword - OFF 


OFF 

Disables output to the left audio channel. 


SET (Videodisc Player Command) Keyword - RIGHT 


RIGHT 

Applies to the right channel. 

Specify ON or OFF with the RIGFIT keyword. 


SET (Videodisc Player Command) Keyword - ON 


ON 

Enables output to the right audio channel. 


SET (Videodisc Player Command) Keyword - OFF 


OFF 


Disables output to the right audio channel. 



SET (Videodisc Player Command) Keyword - DISPLAY ON 


DISPLAY ON 

Enables on-screen information display. 


SET (Videodisc Player Command) Keyword - DISPLAY OFF 


DISPLAY OFF 

Disables on-screen information display. 


SET (Videodisc Player Command) Keyword - DOOR OPEN 


DOOR OPEN 

Opens the door and ejects the tray, if possible. 


SET (Videodisc Player Command) Keyword - DOOR 
CLOSED 


DOOR CLOSED 

Retracts the tray and closes the door, if possible. 


SET (Videodisc Player Command) Keyword - SPEED 
FORMAT PERCENTAGE 


SPEED FORMAT PERCENTAGE 

Sets the speed format to percentage. 


SET (Videodisc Player Command) Keyword - SPEED 
FORMAT FPS 



SPEED FORMAT FPS 

The speed format to frames per second. 


SET (Videodisc Player Command) Keyword - TIME FORMAT 
MILLISECONDS 


TIME FORMAT MILLISECONDS 

Sets the position format to milliseconds. All position information is this format following this command. You can abbreviate 
milliseconds as ms. 


SET (Videodisc Player Command) Keyword - TIME FORMAT 
MMTIME 


TIME FORMAT MMTIME 

Sets the time position format to MMTIME. 


SET (Videodisc Player Command) Keyword - TIME FORMAT 
FRAMES 


TIME FORMAT FRAMES 

Sets the position format to frames. All position information is specified in frames following this command. When the device is opened, 
frames is the default mode for videodisc devices. 


SET (Videodisc Player Command) Keyword - TIME FORMAT 
HMS 


TIME FORMAT HMS 

Sets position format to h.mm.ss, where h is hours, mm is minutes, and ss is seconds. All position information is specified in this 
format following this command. The h input can be omitted if it is equal to 0, mm can be omitted if both mm and h equal 0. 


SET (Videodisc Player Command) Keyword - TIME FORMAT 



HMSF 


TIME FORMAT HMSF 

Sets time format to hours, minutes, seconds, and frames. All position information is this format following this command. 


SET (Videodisc Player Command) Keyword - VIDEO ON 


VIDEO ON 

Enables video output. 


SET (Videodisc Player Command) Keyword - VIDEO OFF 


VIDEO OFF 

Disables video output. 


SET (Videodisc Player Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SET (Videodisc Player Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SET (Videodisc Player Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 


Device type 


• Device name 

• Filename 

• Alias 

AUDIO 

Specifies the audio attributes of the device context determined by the ALL, LEFT, and FtIGFIT keywords. 

ALL 

Applies to both or all of the channels (default). 

Specify ON or OFF with the ALL keyword. 

ON 

Enables audio. 

OFF 

Disables audio. 

LEFT 

Applies to the left channel. 

Specify ON or OFF with the LEFT keyword. 

ON 

Enables output to the left audio channel. 

OFF 

Disables output to the left audio channel. 

RIGHT 

Applies to the right channel. 

Specify ON or OFF with the RIGFIT keyword. 

ON 

Enables output to the right audio channel. 

OFF 

Disables output to the right audio channel. 


DISPLAY ON 

Enables on-screen information display. 


DISPLAY OFF 

Disables on-screen information display. 


DOOR OPEN 

Opens the door and ejects the tray, if possible. 


DOOR CLOSED 

Retracts the tray and closes the door, if possible. 


SPEED FORMAT PERCENTAGE 

Sets the speed format to percentage. 


SPEED FORMAT FPS 

The speed format to frames per second. 


TIME FORMAT MILLISECONDS 

Sets the position format to milliseconds. All position information is this format following this command. You can abbreviate 
milliseconds as ms. 

TIME FORMAT MMTIME 

Sets the time position format to MMTIME. 

TIME FORMAT FRAMES 


Sets the position format to frames. All position information is specified in frames following this command. When the device is opened, 
frames is the default mode for videodisc devices. 


TIME FORMAT HMS 

Sets position format to h.mm.ss, where h is hours, mm is minutes, and ss is seconds. All position information is specified in this 
format following this command. The h input can be omitted if it is equal to 0, mm can be omitted if both mm and h equal 0. 



TIME FORMAT HMSF 

Sets time format to hours, minutes, seconds, and frames. All position information is this format following this command. 

VIDEO ON 

Enables video output. 

VIDEO OFF 

Disables video output. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SET (Videodisc Player Command) - Syntax Diagram 


SET object 


AUDIO 


ALL 

ON 


OFF 

LEFT 

ON 


OFF 

RIGHT 

ON 


OFF 


DISPLAY ON 
DISPLAY OFF 
DOOR OPEN 
DOOR CLOSED 

SPEED FORMAT PERCENTAGE 
SPEED FORMAT FPS 
TIME FORMAT FRAMES 
TIME FORMAT HMS 
TIME FORMAT HMSF 
TIME FORMAT MILLISECONDS 
TIME FORMAT MMTIME 
VIDEO ON 
VIDEO OFF 


WAIT 

NOTIFY 


Examples 


SET (Videodisc Player Command) - Topics 


Select an item: 

Purpose 

Syntax Diagram 

Keywords 

Example 

Glossary 



SPIN 


SPIN (Videodisc Player Command) - Example 


spin videodisc up wait 


SPIN (Videodisc Player Command) - Purpose 


The SPIN command starts the disc spinning or stops the disc from spinning. 


SPIN (Videodisc Player Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


SPIN (Videodisc Player Command) Keyword - DOWN 


DOWN 

Stops the disc from spinning. 


SPIN (Videodisc Player Command) Keyword - UP 


UP 

Starts the disc spinning. 



SPIN (Videodisc Player Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SPIN (Videodisc Player Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SPIN (Videodisc Player Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


DOWN 

Stops the disc from spinning. 

UP 

Starts the disc spinning. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SPIN (Videodisc Player Command) - Syntax Diagram 


SPIN object DOWN 

UP WAIT 

NOTIFY 


Examples 
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STATUS 


STATUS (Videodisc Player Command) - Example 


status videodisc media present wait 


STATUS (Videodisc Player Command) - Purpose 


The STATUS command obtains status information for the device. 


STATUS (Videodisc Player Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


STATUS (Videodisc Player Command) Keyword - CURRENT 
TRACK 


CURRENT TRACK 

Returns the current chapter if applicable. 


STATUS (Videodisc Player Command) Keyword - DISC SIZE 


DISC SIZE 

Returns either 8 or 12 to indicate the size of the loaded disc in inches. 


STATUS (Videodisc Player Command) Keyword - FORWARD 


FORWARD 

Returns TRUE if the play direction is forward or if the device is not playing; FALSE if the play direction is backward. 


STATUS (Videodisc Player Command) Keyword - LENGTH 


LENGTH 

Returns the total length of the segment. 


STATUS (Videodisc Player Command) Keyword - LENGTH 
TRACK number 


LENGTH TRACK number 

Returns unsupported function. 


STATUS (Videodisc Player Command) Keyword - MEDIA 
PRESENT 


MEDIA PRESENT 

Returns TRUE if the media is inserted in the device; otherwise, the return is FALSE. 



STATUS (Videodisc Player Command) Keyword - MEDIA 
TYPE 


MEDIA TYPE 

Returns either CAV, CLV, or other, depending on the type of videodisc. 


STATUS (Videodisc Player Command) Keyword - MODE 


MODE 

Returns not ready, paused, playing, recording, seeking, or stopped or other. 


STATUS (Videodisc Player Command) Keyword - NUMBER 
OF TRACKS 


NUMBER OF TRACKS 

Returns the number of tracks on the media. 


STATUS (Videodisc Player Command) Keyword - POSITION 


POSITION 

Returns the current position. 


STATUS (Videodisc Player Command) Keyword - POSITION 
TRACK number 


POSITION TRACK number 

Returns unsupported function. 


STATUS (Videodisc Player Command) Keyword - READY 



READY 

Returns TRUE if the device is ready. 


STATUS (Videodisc Player Command) Keyword - SIDE 


SIDE 

Returns 1 or 2 to indicate which side of the disc is loaded. 


STATUS (Videodisc Player Command) Keyword - SPEED 


SPEED 

Returns the speed in the currently specified speed format. 


STATUS (Videodisc Player Command) Keyword - SPEED 
FORMAT 


SPEED FORMAT 

Returns the speed format. 


STATUS (Videodisc Player Command) Keyword - START 
POSITION 


START POSITION 

Returns the starting position of the media. 


STATUS (Videodisc Player Command) Keyword - TIME 
FORMAT 


TIME FORMAT 

Returns the time format. 



STATUS (Videodisc Player Command) Keyword - VOLUME 


VOLUME 

Returns the current volume setting. The volume is returned as a string in the format /eft.r/ght where /eft and right are percentages of 
the maximum achievable effect for the left and right channels respectively. Leading zeros are suppressed for the volume level in each 
channel. 


STATUS (Videodisc Player Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


STATUS (Videodisc Player Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (Videodisc Player Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

CURRENT TRACK 

Returns the current chapter if applicable. 

DISC SIZE 

Returns either 8 or 12 to indicate the size of the loaded disc in inches. 

FORWARD 

Returns TRUE if the play direction is forward or if the device is not playing; FALSE if the play direction is backward. 

LENGTH 

Returns the total length of the segment. 

LENGTH TRACK number 

Returns unsupported function. 


MEDIA PRESENT 

Returns TRUE if the media is inserted in the device; otherwise, the return is FALSE. 

MEDIA TYPE 

Returns either CAV, CLV, or other, depending on the type of videodisc. 

MODE 

Returns not ready, paused, playing, recording, seeking, or stopped or other. 

NUMBER OF TRACKS 

Returns the number of tracks on the media. 

POSITION 

Returns the current position. 

POSITION TRACK number 

Returns unsupported function. 

READY 

Returns TRUE if the device is ready. 

SIDE 

Returns 1 or 2 to indicate which side of the disc is loaded. 

SPEED 

Returns the speed in the currently specified speed format. 

SPEED FORMAT 

Returns the speed format. 

START POSITION 

Returns the starting position of the media. 

TIME FORMAT 

Returns the time format. 

VOLUME 

Returns the current volume setting. The volume is returned as a string in the format ieft.right where /eft and right are percentages of 
the maximum achievable effect for the left and right channels respectively. Leading zeros are suppressed for the volume level in each 
channel. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (Videodisc Player Command) - Syntax Diagram 


STATUS object CURRENT TRACK 

DISC SIZE WAIT 

FORWARD NOTIFY 

LENGTH 

LENGTH TRACK number 
MEDIA PRESENT 
MEDIA TYPE 
MODE 

NUMBER OF TRACKS 
POSITION 

POSITION TRACK number 

READY 

SIDE 


SPEED 

SPEED FORMAT 
START POSITION 
TIME FORMAT 
VOLUME 


Examples 
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STEP 


STEP (Videodisc Player Command) - Example 

step videodisc reverse wait 


STEP (Videodisc Player Command) - Purpose 


The STEP command steps the play one or more frames forward or backward. The default action is to step one time unit forward. This 
command applies only to CAV discs. 


STEP (Videodisc Player Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 


Device type 
Device name 



Filename 

Alias 


STEP (Videodisc Player Command) Keyword - REVERSE 


REVERSE 

Steps the frames in reverse. Only steps to l-frames. 


STEP (Videodisc Player Command) Keyword - BY frames 


BY frames 

Indicates the number of frames to step. 


STEP (Videodisc Player Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


STEP (Videodisc Player Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STEP (Videodisc Player Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


REVERSE 


Steps the frames in reverse. Only steps to l-frames. 


BY frames 

Indicates the number of frames to step. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STEP (Videodisc Player Command) - Syntax Diagram 


STEP object REVERSE 

BY frames 


WAIT 

NOTIFY 


Examples 


STEP (Videodisc Player Command) - Topics 
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Video Overlay Commands 


The video overlay commands are the commands supported by the video overlay device for analog video. Information specific to the 
M-Motion Video Adapter/A, such as default values, is also provided. 

The video overlay device for analog video supports the following device-type specific commands and extensions to the following basic and 
required commands: 


• CAPABILITY 

• CAPTURE 

• CONNECTOR 
FREEZE 

• INFO 
LOAD 

• OPEN 

• PUT 

• RESTORE 



• SAVE 
SET 

• STATUS 
UNFREEZE 

• WHERE 
WINDOW 


CAPABILITY 


CAPABILITY (Video Overlay Command) - Example 


capability videooverlay can distort wait 


CAPABILITY (Video Overlay Command) - Purpose 


The CAPABILITY command requests information about the capabilities of the video overlay device driver. 


CAPABILITY (Video Overlay Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CAPABILITY (Video Overlay Command) Keyword - CAN 
DISTORT 


CAN DISTORT 

Returns TRUE if the device can stretch and display incoming video independently in horizontal and vertical dimensions. 


CAPABILITY (Video Overlay Command) Keyword - CAN 
EJECT 


CAN EJECT 

Returns FALSE. 


CAPABILITY (Video Overlay Command) Keyword - CAN 
FREEZE 


CAN FREEZE 

Returns TRUE if the device can freeze data in the frame buffer. 


CAPABILITY (Video Overlay Command) Keyword - CAN 
LOCKEJECT 


CAN LOCKEJECT 

Returns FALSE. 


CAPABILITY (Video Overlay Command) Keyword - CAN 
OVERLAY GRAPHICS 


CAN OVERLAY GRAPHICS 

Returns TRUE if the device can display graphics over video. 


CAPABILITY (Video Overlay Command) Keyword - CAN 
PLAY 


CAN PLAY 

Returns FALSE. 



CAPABILITY (Video Overlay Command) Keyword - CAN 
RECORD 


CAN RECORD 

Returns FALSE. The overlay device cannot record. Flowever, the external device connected to the overlay device might be able to 
record. 


CAPABILITY (Video Overlay Command) Keyword - CAN 
SAVE 


CAN SAVE 

Returns TRUE if the device can save video still image frames to a file. 


CAPABILITY (Video Overlay Command) Keyword - CAN 
SETVOLUME 


CAN SETVOLUME 

Returns FALSE. Video overlay devices do not control audio. 


CAPABILITY (Video Overlay Command) Keyword - CAN 
STRETCH 


CAN STRETCH 

Returns TRUE if the device can stretch or shrink video to fill a given display rectangle. 


CAPABILITY (Video Overlay Command) Keyword - 
COMPOUND DEVICE 


COMPOUND DEVICE 

Returns TRUE. 



CAPABILITY (Video Overlay Command) Keyword - DEVICE 
TYPE 


DEVICE TYPE 

Returns OVERLAY. 


CAPABILITY (Video Overlay Command) Keyword - HAS 
AUDIO 


HAS AUDIO 

Returns FALSE. Control of audio mixing on video overlay hardware is performed through the amp-mixer device. 


CAPABILITY (Video Overlay Command) Keyword - HAS 
IMAGE 


HAS IMAGE 

Returns TRUE if the device supports still image functions. 


CAPABILITY (Video Overlay Command) Keyword - HAS 
VIDEO 


HAS VIDEO 

Returns TRUE. 


CAPABILITY (Video Overlay Command) Keyword - 
HORIZONTAL IMAGE EXTENT 


HORIZONTAL IMAGE EXTENT 

Returns the maximum horizontal (X) extent for still image capture. 


M-Motion specific: Returns 640. 



CAPABILITY (Video Overlay Command) Keyword - 
HORIZONTAL SOURCE EXTENT 


HORIZONTAL SOURCE EXTENT 

Returns the maximum horizontal (X) extent for the video source. 

M-Motion specific: Returns 706 for both NTSC and PAL video. 


CAPABILITY (Video Overlay Command) Keyword - 
MESSAGE command 


MESSAGE command 

Returns TRUE if the overlay device supports the command specified by command. The command can be any string command such 
as OPEN, PLAY, and so on. 


CAPABILITY (Video Overlay Command) Keyword - 
PREROLL TIME 


PREROLL TIME 

Returns 0. 


CAPABILITY (Video Overlay Command) Keyword - 
PREROLL TYPE 


PREROLL TYPE 

Returns the preroll characteristics of the device. Returns NONE. 


CAPABILITY (Video Overlay Command) Keyword - USES 
FILES 


USES FILES 



Returns TRUE if the device accepts file names for loading and saving images. 


CAPABILITY (Video Overlay Command) Keyword - 
VERTICAL IMAGE EXTENT 


VERTICAL IMAGE EXTENT 

Returns the maximum vertical (Y) extent for still image capture. 

M-Motion specific: Returns 480. 


CAPABILITY (Video Overlay Command) Keyword - 
VERTICAL SOURCE EXTENT 


VERTICAL SOURCE EXTENT 

Returns the maximum vertical (Y) extent for the video source. 

M-Motion specific: Returns 484 for NTSC video or 564 for PAL video. 


CAPABILITY (Video Overlay Command) Keyword - 
WINDOWS 


WINDOWS 

Returns an integer for the maximum number of windows that the device can support concurrently. 

M-Motion specific: Returns 10. 


CAPABILITY (Video Overlay Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


CAPABILITY (Video Overlay Command) Keyword - NOTIFY 



NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPABILITY (Video Overlay Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 

CAN DISTORT 

Returns TRUE if the device can stretch and display incoming video independently in horizontal and vertical dimensions. 

CAN EJECT 

Returns FALSE. 

CAN FREEZE 

Returns TRUE if the device can freeze data in the frame buffer. 

CAN LOCKEJECT 

Returns FALSE. 

CAN OVERLAY GRAPHICS 

Returns TRUE if the device can display graphics over video. 

CAN PLAY 

Returns FALSE. 

CAN RECORD 

Returns FALSE. The overlay device cannot record. Flowever, the external device connected to the overlay device might be able to 
record. 

CAN SAVE 

Returns TRUE if the device can save video still image frames to a file. 

CAN SETVOLUME 

Returns FALSE. Video overlay devices do not control audio. 

CAN STRETCH 

Returns TRUE if the device can stretch or shrink video to fill a given display rectangle. 

COMPOUND DEVICE 

Returns TRUE. 

DEVICE TYPE 

Returns OVERLAY. 

HAS AUDIO 

Returns FALSE. Control of audio mixing on video overlay hardware is performed through the amp-mixer device. 

HAS IMAGE 

Returns TRUE if the device supports still image functions. 

HAS VIDEO 

Returns TRUE. 

HORIZONTAL IMAGE EXTENT 

Returns the maximum horizontal (X) extent for still image capture. 


M-Motion specific: Returns 640. 


HORIZONTAL SOURCE EXTENT 

Returns the maximum horizontal (X) extent for the video source. 

M-Motion specific: Returns 706 for both NTSC and PAL video. 

MESSAGE command 

Returns TRUE if the overlay device supports the command specified by command. The command can be any string command such 
as OPEN, PLAY, and so on. 

PREROLL TIME 

Returns 0. 

PREROLL TYPE 

Returns the preroll characteristics of the device. Returns NONE. 

USES FILES 

Returns TRUE if the device accepts file names for loading and saving images. 

VERTICAL IMAGE EXTENT 

Returns the maximum vertical (Y) extent for still image capture. 

M-Motion specific: Returns 480. 

VERTICAL SOURCE EXTENT 

Returns the maximum vertical (Y) extent for the video source. 

M-Motion specific: Returns 484 for NTSC video or 564 for PAL video. 

WINDOWS 

Returns an integer for the maximum number of windows that the device can support concurrently. 

M-Motion specific: Returns 10. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPABILITY (Video Overlay Command) - Syntax Diagram 
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CAPTURE 


CAPTURE (Video Overlay Command) - Example 


capture videooverlay at 100 100 260 220 wait 


CAPTURE (Video Overlay Command) - Purpose 


The CAPTURE command captures the current video image. This does not cause the image or bit map to be saved: the application must 
subsequently issue a SAVE command to save the device element. The device will freeze motion temporarily if needed to capture the image 
and put the image into the image device element. Repeated capture operations will overwrite the image contained in this temporary space. 
The device will wait for a SAVE command to transfer the information to a file, or MCI_GETIMAGEBUFFER to supply an application with a 
copy of the image buffer. 

Note: If no rectangle is specified, the entire rectangle is captured. 


CAPTURE (Video Overlay Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 



Device type 
Device name 
Filename 
Alias 


CAPTURE (Video Overlay Command) Keyword - AT rect 


AT rect 

Specifies a rectangle relative to the window origin in device coordinates. The rectangle is specified as XI Y1 X2 Y2. The coordinates 
XI Y1 specify the lower-left corner and X2 Y2 specify the upper-right corner. Only the video in that subregion will be captured. 


CAPTURE (Video Overlay Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CAPTURE (Video Overlay Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPTURE (Video Overlay Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


AT rect 

Specifies a rectangle relative to the window origin in device coordinates. The rectangle is specified as XI Y1 X2 Y2. The coordinates 
XI Y1 specify the lower-left corner and X2 Y2 specify the upper-right corner. Only the video in that subregion will be captured. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPTURE (Video Overlay Command) - Syntax Diagram 


CAPTURE object 


AT rect 


WAIT 

NOTIFY 


Examples 
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CONNECTOR 


CONNECTOR (Video Overlay Command) - Example 


connector videooverlay query number 2 wait 


CONNECTOR (Video Overlay Command) - Purpose 


The CONNECTOR command enables, disables, or queries the status of connector on a device. 


CONNECTOR (Video Overlay Command) Keyword - object 



object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CONNECTOR (Video Overlay Command) Keyword - ENABLE 


ENABLE 

Enables information flow through the indicated connector. Use of this keyword requires that the NUMBER or TYPE keywords must 
also be specified. 


CONNECTOR (Video Overlay Command) Keyword - 
DISABLE 


DISABLE 

Disables information flow through the indicated connector. Use of this keyword requires that the NUMBER or TYPE keywords must 
also be specified. 


CONNECTOR (Video Overlay Command) Keyword - QUERY 


QUERY 

Queries the state of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled 
respectively. Use of this keyword requires that the NUMBER or TYPE keywords must also be specified. 


CONNECTOR (Video Overlay Command) Keyword - 
NUMBER connector number 


NUMBER connector number 

Indicates the connector number on which to perform the requested action. If this item is omitted, then the first connector is assumed. 
If the TYPE item is included, then the connector number is interpreted as a relative offset within the specified connector type. 


CONNECTOR (Video Overlay Command) Keyword - TYPE 



connector_type 


TYPE connectortype 

Indicates the type of connector to which the requested action applies. The connector types are defined by each device. 


CONNECTOR (Video Overlay Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CONNECTOR (Video Overlay Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTOR (Video Overlay Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

ENABLE 

Enables information flow through the indicated connector. Use of this keyword requires that the NUMBER or TYPE keywords must 
also be specified. 

DISABLE 

Disables information flow through the indicated connector. Use of this keyword requires that the NUMBER or TYPE keywords must 
also be specified. 

QUERY 

Queries the state of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled 
respectively. Use of this keyword requires that the NUMBER or TYPE keywords must also be specified. 

NUMBER connectornumber 

Indicates the connector number on which to perform the requested action. If this item is omitted, then the first connector is assumed. 
If the TYPE item is included, then the connector number is interpreted as a relative offset within the specified connector type. 

TYPE connector type 

Indicates the type of connector to which the requested action applies. The connector types are defined by each device. 


WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 


application. 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTOR (Video Overlay Command) - Syntax Diagram 
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FREEZE 


FREEZE (Video Overlay Command) - Example 


freeze videooverlay at 100 100 260 220 wait 


FREEZE (Video Overlay Command) - Purpose 



The FREEZE command stops updating the video buffer by the video source. Supported only if can freeze returns TRUE. 


FREEZE (Video Overlay Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


FREEZE (Video Overlay Command) Keyword - AT rect 


AT rect 

Specifies a rectangle relative to the window origin in device coordinates. The rectangle array is specified as XI Y1 X2 Y2. The 
coordinates XI Y1 specify the lower-left corner and X2 Y2 specify the upper-right corner. Only the video in that subregion will be 
frozen. 


FREEZE (Video Overlay Command) Keyword - OUTSIDE rect 


OUTSIDE rect 

The area outside the specified rectangle is to be affected. 


FREEZE (Video Overlay Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


FREEZE (Video Overlay Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


FREEZE (Video Overlay Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


AT rect 

Specifies a rectangle relative to the window origin in device coordinates. The rectangle array is specified as XI Y1 X2 Y2. The 
coordinates XI Y1 specify the lower-left corner and X2 Y2 specify the upper-right corner. Only the video in that subregion will be 
frozen. 


OUTSIDE rect 

The area outside the specified rectangle is to be affected. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


FREEZE (Video Overlay Command) - Syntax Diagram 
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INFO 


INFO (Video Overlay Command) - Example 


info videooverlay product wait 


INFO (Video Overlay Command) - Purpose 


The INFO command returns string information from the device driver. 


INFO (Video Overlay Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


INFO (Video Overlay Command) Keyword - FILE 


FILE 

Returns the name of the current element. 


INFO (Video Overlay Command) Keyword - IMAGE 


IMAGE 

Specifies an optional keyword indicating image file. 



INFO (Video Overlay Command) Keyword - PRODUCT 


PRODUCT 

Returns the product name and model of the hardware used for the video overlay device. 


INFO (Video Overlay Command) Keyword - WINDOW TEXT 


WINDOW TEXT 

Returns the caption of the video overlay window. 


INFO (Video Overlay Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


INFO (Video Overlay Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


INFO (Video Overlay Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


FILE 

Returns the name of the current element. 

IMAGE 

Specifies an optional keyword indicating image file. 


PRODUCT 

Returns the product name and model of the hardware used for the video overlay device. 

WINDOW TEXT 

Returns the caption of the video overlay window. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


INFO (Video Overlay Command) - Syntax Diagram 
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LOAD 


LOAD (Video Overlay Command) - Example 


load videooverlay picture. vid wait 



LOAD (Video Overlay Command) - Purpose 


The LOAD command loads a new device element (file) into an already open device context and overwrites any image currently stored there. 
It can be displayed using the RESTORE command. The file will be opened, accessed, and closed on this command. If the format of the 
image file is not recognizable as either a device specific file format or a format supported by MMIO, the load will fail. 


LOAD (Video Overlay Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


LOAD (Video Overlay Command) Keyword - filename 


filename 

Specifies the file name to load. 


LOAD (Video Overlay Command) Keyword - IMAGE 


IMAGE 

Specifies an optional keyword indicating an image file. 


LOAD (Video Overlay Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


LOAD (Video Overlay Command) Keyword - NOTIFY 



NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


LOAD (Video Overlay Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

filename 

Specifies the file name to load. 

IMAGE 

Specifies an optional keyword indicating an image file. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


LOAD (Video Overlay Command) - Syntax Diagram 
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OPEN 


OPEN (Video Overlay Command) - Example 


open videooverlay alias vd shareable wait 


OPEN (Video Overlay Command) - Purpose 


The OPEN command opens the video overlay device. 


OPEN (Video Overlay Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


OPEN (Video Overlay Command) Keyword - ALIAS 
device alias 


ALIAS device_alias 

Specifies an alternate name for the device. If specified, it must also be used for subsequent references. 


OPEN (Video Overlay Command) Keyword - DOSQUEUE 


DOSQUEUE 

If a device instance is opened with the DOSQUEUE keyword specified, window handles that are passed in for the instance will be 
treated as OS/2 Control Program queue handles. 


OPEN (Video Overlay Command) Keyword - PARENT hwnd 


PARENT hwnd 

Specifies the window handle of the parent window. If specified, it is used as the parent window of the digital video device default 
window. 


OPEN (Video Overlay Command) Keyword - READONLY 


READONLY 

Specifies that the file is to be opened in read-only mode. 


OPEN (Video Overlay Command) Keyword - SHAREABLE 


SHAREABLE 

Initializes the device as shareable. Specifying SHAREABLE makes the resources of the device available to other device contexts. If 
SHAREABLE is not specified on OPEN, the resource will be exclusively acquired when the device is opened. 


OPEN (Video Overlay Command) Keyword - TYPE 
device_type 


TYPE device_type 

Specifies the compound device used to control a device element. As an alternative to TYPE, the media control interface can use the 
extended attributes or file extensions associated with the file to select the controlling device. 


OPEN (Video Overlay Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 



OPEN (Video Overlay Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


OPEN (Video Overlay Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

ALIAS device_alias 

Specifies an alternate name for the device. If specified, it must also be used for subsequent references. 

DOSQUEUE 

If a device instance is opened with the DOSQUEUE keyword specified, window handles that are passed in for the instance will be 
treated as OS/2 Control Program queue handles. 

PARENT hwnd 

Specifies the window handle of the parent window. If specified, it is used as the parent window of the digital video device default 
window. 

READONLY 

Specifies that the file is to be opened in read-only mode. 

SHAREABLE 

Initializes the device as shareable. Specifying SHAREABLE makes the resources of the device available to other device contexts. If 
SHAREABLE is not specified on OPEN, the resource will be exclusively acquired when the device is opened. 

TYPE device_type 

Specifies the compound device used to control a device element. As an alternative to TYPE, the media control interface can use the 
extended attributes or file extensions associated with the file to select the controlling device. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


OPEN (Video Overlay Command) - Syntax Diagram 
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PUT 


PUT (Video Overlay Command) - Example 

put videooverlay source wait 


PUT (Video Overlay Command) - Purpose 


The PUT command sets the source and destination rectangles for the video and sets the size and position of the video window. 

Warning: Setting the source rectangle smaller than the destination rectangle size might result in unpredictable video remnants appearing 
the video window. Sizing the video window larger than the current source rectangle size might also produce this effect. 


PUT (Video Overlay Command) Keyword - object 



object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


PUT (Video Overlay Command) Keyword - SOURCE 


SOURCE 

Sets the source rectangle to the default size and position. The source rectangle specifies the portion of the video source which will be 
displayed and is relative to the lower-left corner of the video source. 


PUT (Video Overlay Command) Keyword - DESTINATION 


DESTINATION 

Sets the default destination rectangle to the size of the video window. Therefore, the entire video window displays video. This 
destination rectangle will automatically be adjusted as the window is sized. 


PUT (Video Overlay Command) Keyword - SOURCE 
DESTINATION 


SOURCE DESTINATION 

Sets both the source and destination rectangles to their respective defaults. 


PUT (Video Overlay Command) Keyword - SOURCE AT rect 


SOURCE AT rect 

The source clipping rectangle specifies the portion of the source video which will be displayed. The rectangle is relative to the 
lower-left corner of the video source. 


PUT (Video Overlay Command) Keyword - DESTINATION AT 
rect 



DESTINATION AT rect 

The destination rectangle specifies where in the video window that video will be displayed. All areas within the video window that are 
outside the destination rectangle will be frozen. 

The rectangle is relative to the window origin and is specified as XI Y1 X2 Y2. The coordinates XI Y1 specify the lower-left corner 
and X2 Y2 specify the upper-right corner. 


PUT (Video Overlay Command) Keyword - WINDOW AT rect 


WINDOW AT rect 

Moves and/or sizes the default video window by specifying a valid rectangle and the following options: 

Note: The MOVE and SIZE keywords can both be specified, in which case, the default video window is moved and sized at the same 
time. 


PUT (Video Overlay Command) Keyword - MOVE 


MOVE 

Moves the default video window to the XI Y1 coordinates specified in the rectangle. Window coordinates are relative to the parent 
window. 

Notes: 

(1) All coordinates of the rectangle (XI Y1 X2 Y2) must be specified, but X2 Y2 are ignored if the size option is not specified. 

(2) This option will not affect an application-supplied alternate video window. 


PUT (Video Overlay Command) Keyword - SIZE 


SIZE 

Sizes the default video window to the difference of the coordinates ((X2 - XI ) + 1 ) and ((Y2 - Y1 ) + 1 ). All coordinates of the rectangle 
(XI Y1 X2 Y2) must be specified. 

Note: This option will not affect an application-supplied alternate video window. 


PUT (Video Overlay Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 



PUT (Video Overlay Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


PUT (Video Overlay Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

SOURCE 

Sets the source rectangle to the default size and position. The source rectangle specifies the portion of the video source which will be 
displayed and is relative to the lower-left corner of the video source. 

DESTINATION 

Sets the default destination rectangle to the size of the video window. Therefore, the entire video window displays video. This 
destination rectangle will automatically be adjusted as the window is sized. 

SOURCE DESTINATION 

Sets both the source and destination rectangles to their respective defaults. 

SOURCE AT rect 

The source clipping rectangle specifies the portion of the source video which will be displayed. The rectangle is relative to the 
lower-left corner of the video source. 

DESTINATION AT rect 

The destination rectangle specifies where in the video window that video will be displayed. All areas within the video window that are 
outside the destination rectangle will be frozen. 

The rectangle is relative to the window origin and is specified as XI Y1 X2 Y2. The coordinates XI Y1 specify the lower-left corner 
and X2 Y2 specify the upper-right corner. 

WINDOW AT rect 

Moves and/or sizes the default video window by specifying a valid rectangle and the following options: 

Note: The MOVE and SIZE keywords can both be specified, in which case, the default video window is moved and sized at the same 
time. 

MOVE 

Moves the default video window to the XI Y1 coordinates specified in the rectangle. Window coordinates are 
relative to the parent window. 

Notes: 

(1) All coordinates of the rectangle (XI Y1 X2 Y2) must be specified, but X2 Y2 are ignored if the size option is not 
specified. 

(2) This option will not affect an application-supplied alternate video window. 

SIZE 

Sizes the default video window to the difference of the coordinates ((X2 - XI ) + 1 ) and ((Y2 - Y1 ) + 1 ). All 
coordinates of the rectangle (XI Y1 X2 Y2) must be specified. 

Note: This option will not affect an application-supplied alternate video window. 


WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


PUT (Video Overlay Command) - Syntax Diagram 
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RESTORE 


RESTORE (Video Overlay Command) - Example 


restore videooverlay destination at 100 100 200 200 wait 



RESTORE (Video Overlay Command) - Purpose 


The RESTORE command restores the video image from the currently loaded bitmap or image. The device transfers the image from the 
device element buffer to the display surface. To ensure that the image is displayed, the device automatically performs a FREEZE operation, 
if necessary, on the area covered by the image. 


RESTORE (Video Overlay Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


RESTORE (Video Overlay Command) Keyword - 
DESTINATION AT rect 


DESTINATION AT rect 

Specifies the window subregion where the image is to be restored. The rectangle is relative to the window origin in device 
coordinates and is specified as XI Y1 X2 Y2. The coordinates XI Y1 specify the lower-left corner and X2 Y2 specify the upper-right 
corner. 


RESTORE (Video Overlay Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


RESTORE (Video Overlay Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


RESTORE (Video Overlay Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

DESTINATION AT rect 

Specifies the window subregion where the image is to be restored. The rectangle is relative to the window origin in device 
coordinates and is specified as XI Y1 X2 Y2. The coordinates XI Y1 specify the lower-left corner and X2 Y2 specify the upper-right 
corner. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


RESTORE (Video Overlay Command) - Syntax Diagram 


RESTORE object DESTINATION AT rect 


WAIT 

NOTIFY 


Examples 
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SAVE 



SAVE (Video Overlay Command) - Example 


save videooverlay pic.vid wait 


SAVE (Video Overlay Command) - Purpose 


The SAVE command saves the current image. The device will transfer the image in the image device element to a file, converting where 
possible, to support the current settings. For example, FileFormat, Quality, BitsPerPel and PelFormat. 


SAVE (Video Overlay Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


SAVE (Video Overlay Command) Keyword - filename 


filename 

Specifies the destination path and filename. 


SAVE (Video Overlay Command) Keyword - IMAGE 


IMAGE 

Specifies an optional keyword. 


SAVE (Video Overlay Command) Keyword - WAIT 



WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SAVE (Video Overlay Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SAVE (Video Overlay Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

filename 

Specifies the destination path and filename. 

IMAGE 

Specifies an optional keyword. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SAVE (Video Overlay Command) - Syntax Diagram 


SAVE object filename 

IMAGE WAIT 

NOTIFY 


Examples 
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SET 


SET (Video Overlay Command) - Example 


set videooverlay greyscale on wait 


SET (Video Overlay Command) - Purpose 


The SET command sets the various control and attribute items. 


SET (Video Overlay Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


SET (Video Overlay Command) Keyword - BRIGHTNESS 
level 


BRIGHTNESS level 

Sets the brightness to the specified level (0-100). 

M-Motion specific: The default value is 80. 


SET (Video Overlay Command) Keyword - CONTRAST level 


CONTRAST level 

Sets the contrast to the specified level (0-100). 

M-Motion specific: The default value is 90. 


SET (Video Overlay Command) Keyword - GREYSCALE ON 


GREYSCALE ON 

Enables greyscale. Video is displayed in black and white. 


SET (Video Overlay Command) Keyword - GREYSCALE OFF 


GREYSCALE OFF 

Disables greyscale. Video is displayed in color using the current settings. 

M-Motion specific: The default is off. 


SET (Video Overlay Command) Keyword - HUE level 


HUE level 

Sets the hue to the specified level (0 - 100). A value of 50 specifies neutral hue, which is the default. Hue is also referred to as "tint." 

M-Motion specific: The default is 50. 


SET (Video Overlay Command) Keyword - IMAGE 
BITSPERPEL count 


IMAGE BITSPERPEL count 



Sets the number of bits per pixel for saving bit maps. 
M-Motion specific: The default value is 12. 


SET (Video Overlay Command) Keyword - IMAGE 
PELFORMAT type 


IMAGE PELFORMAT type 

Sets the pel format or color encoding method for saving bit maps and images specified by the four-character code (FOURCC), such 
as yuvb or rgbb. 

M-Motion specific: The default is yuvb. 


SET (Video Overlay Command) Keyword - IMAGE FILE 
FORMAT format 


IMAGE FILE FORMAT format 

Sets the specific image file format in which the image capture is to be stored (when "saved"). This format must be specified by a 
four-character code (FOURCC), for example, MMOT or OS13, and must be one of the currently supported and installed MMIO image 
file formats, or the device-specific format. This does not effect the loading or restoring of images. It overwrites any previous file-format 
value, such as that obtained through a LOAD operation. 

M-Motion specific: The default is MMOT. 


SET (Video Overlay Command) Keyword - IMAGE 
COMPRESSION type 


IMAGE COMPRESSION type 

Sets the compression type to be used for saving images if possible. Possible values for type include: none. 
M-Motion specific: The default is none. 

The following type values are not supported: 

• pic9 

• picl 6 

• jpeg9 

• jpegn 

• rle4 

• rle8 


SET (Video Overlay Command) Keyword - IMAGE QUALITY 



level 


IMAGE QUALITY level 

Sets the specified still image quality level. Used for optimizing the auto-selection of compression type when saving to file formats. 


high Indicates photo-like image quality. 

med Indicates that the image has moderate complexity or quality, 

low Indicates a lower color or complexity image. 


M-Motion specific: The default is high. 


SET (Video Overlay Command) Keyword - SATURATION 
level 


SATURATION level 

Sets the saturation to the specified level (0-100). Saturation is also referred to as "color." 
M-Motion specific: The default value is 65. 


SET (Video Overlay Command) Keyword - SHARPNESS 
level 


SHARPNESS level 

Sets the sharpness to the specified level (0-100). 

M-Motion specific: The default value is 80. 


SET (Video Overlay Command) Keyword - VIDEO ON 

VIDEO ON 

Enables video output. 


SET (Video Overlay Command) Keyword - VIDEO OFF 


VIDEO OFF 

Disables video output. The video window will be black. The following operations have no effect if video is set off: CAPTURE, 
RESTORE, FREEZE, and UNFREEZE. 



SET (Video Overlay Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SET (Video Overlay Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SET (Video Overlay Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

BRIGHTNESS level 

Sets the brightness to the specified level (0-100). 

M-Motion specific: The default value is 80. 

CONTRAST level 

Sets the contrast to the specified level (0-1 00). 

M-Motion specific: The default value is 90. 

GREYSCALE ON 

Enables greyscale. Video is displayed in black and white. 

GREYSCALE OFF 

Disables greyscale. Video is displayed in color using the current settings. 

M-Motion specific: The default is off. 

HUE level 

Sets the hue to the specified level (0 - 100). A value of 50 specifies neutral hue, which is the default. Flue is also referred to as "tint." 

M-Motion specific: The default is 50. 

IMAGE BITSPERPEL count 

Sets the number of bits per pixel for saving bit maps. 

M-Motion specific: The default value is 12. 

IMAGE PELFORMAT type 

Sets the pel format or color encoding method for saving bit maps and images specified by the four-character code (FOURCC), such 


as yuvb or rgbb. 


M-Motion specific: The default is yuvb. 

IMAGE FILE FORMAT format 

Sets the specific image file format in which the image capture is to be stored (when "saved"). This format must be specified by a 
four-character code (FOURCC), for example, MMOT or OS13, and must be one of the currently supported and installed MMIO image 
file formats, or the device-specific format. This does not effect the loading or restoring of images. It overwrites any previous file-format 
value, such as that obtained through a LOAD operation. 

M-Motion specific: The default is MMOT. 

IMAGE COMPRESSION type 

Sets the compression type to be used for saving images if possible. Possible values for type include: none. 

M-Motion specific: The default is none. 

The following type values are not supported: 

• pic9 

• picl 6 
jpeg9 

• jpegn 

■ rle4 

• rle8 


IMAGE QUALITY level 

Sets the specified still image quality level. Used for optimizing the auto-selection of compression type when saving to file formats. 


high Indicates photo-like image quality. 

med Indicates that the image has moderate complexity or quality, 

low Indicates a lower color or complexity image. 


M-Motion specific: The default is high. 


SATURATION level 

Sets the saturation to the specified level (0-100). Saturation is also referred to as "color." 


M-Motion specific: The default value is 65. 


SHARPNESS level 

Sets the sharpness to the specified level (0-100). 


M-Motion specific: The default value is 80. 

VIDEO ON 

Enables video output. 


VIDEO OFF 

Disables video output. The video window will be black. The following operations have no effect if video is set off: CAPTURE, 
RESTORE, FREEZE, and UNFREEZE. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


SET (Video Overlay Command) - Syntax Diagram 


SET 


object 


BRIGHTNESS level 
CONTRAST level 


WAIT 


NOTIFY 


GREYSCALE ON 
GREYSCALE OFF 
HUE level 

IMAGE BITSPERPEL count 
IMAGE PELFORMAT type 
SATURATION level 
SHARPNESS level 
IMAGE FILE FORMAT format 
IMAGE COMPRESSION type 
IMAGE QUALITY level 
VIDEO ON 
VIDEO OFF 


Examples 
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STATUS 


STATUS (Video Overlay Command) - Example 


status videooverlay hue wait 


STATUS (Video Overlay Command) - Purpose 


The STATUS command obtains status information for the device and returns the current settings. These values might have been changed 
through previous SET operations, LOAD image operations, or the device defaults. 


STATUS (Video Overlay Command) Keyword - object 



object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


STATUS (Video Overlay Command) Keyword - 
BRIGHTNESS 


BRIGHTNESS 

Returns the brightness level. 


STATUS (Video Overlay Command) Keyword - CONTRAST 


CONTRAST 

Returns the contrast level. 


STATUS (Video Overlay Command) Keyword - GREYSCALE 


GREYSCALE 

Returns ON or OFF. 


STATUS (Video Overlay Command) Keyword - HORIZONTAL 
IMAGE EXTENT 


HORIZONTAL IMAGE EXTENT 

Returns the horizontal (X) source extent for the currently loaded image. 


STATUS (Video Overlay Command) Keyword - HUE 



HUE 


Returns the hue level. 


STATUS (Video Overlay Command) Keyword - IMAGE 
BITSPERPEL 


IMAGE BITSPERPEL 

Returns the number of bits per pixel for saving bit maps and images. 


STATUS (Video Overlay Command) Keyword - IMAGE 
COMPRESSION 


IMAGE COMPRESSION 

Returns the compression type used for saving bit maps and images. 


STATUS (Video Overlay Command) Keyword - IMAGE FILE 
FORMAT 


IMAGE FILE FORMAT 

Returns the image file format. 


STATUS (Video Overlay Command) Keyword - IMAGE 
PELFORMAT 


IMAGE PELFORMAT 

Returns the pel format for saving bit maps and images. 


STATUS (Video Overlay Command) Keyword - IMAGE 
QUALITY 



IMAGE QUALITY 

Returns the still image quality level. 


STATUS (Video Overlay Command) Keyword - MODE 


MODE 

Returns OTHER. 


STATUS (Video Overlay Command) Keyword - READY 


READY 

Returns TRUE. 


STATUS (Video Overlay Command) Keyword - SATURATION 


SATURATION 

Returns the saturation level. 


STATUS (Video Overlay Command) Keyword - SHARPNESS 


SHARPNESS 

Returns the sharpness level. 


STATUS (Video Overlay Command) Keyword - TIME 
FORMAT 


TIME FORMAT 

Returns the time format. 


STATUS (Video Overlay Command) Keyword - 



TRANSPARENT COLOR 


TRANSPARENT COLOR 

Returns the transparency color value, relative to the transparency type. Video displays through all pels of this color. 
M-Motion specific: Returns 3 (CLR_PINK). 


STATUS (Video Overlay Command) Keyword - 
TRANSPARENT TYPE 


TRANSPARENT TYPE 

Returns the type of transparency supported (if any), such as RGB value or palette entry. 

M-Motion specific: Returns PALETTE. 


STATUS (Video Overlay Command) Keyword - VERTICAL 
IMAGE EXTENT 


VERTICAL IMAGE EXTENT 

Returns the vertical (Y) source extent for the currently loaded image. 


STATUS (Video Overlay Command) Keyword - WINDOW 
HANDLE 


WINDOW HANDLE 

Returns the window handle of the overlay video window in the low word of the return value. 


STATUS (Video Overlay Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


STATUS (Video Overlay Command) Keyword - NOTIFY 



NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (Video Overlay Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

BRIGHTNESS 

Returns the brightness level. 

CONTRAST 

Returns the contrast level. 

GREYSCALE 

Returns ON or OFF. 

HORIZONTAL IMAGE EXTENT 

Returns the horizontal (X) source extent for the currently loaded image. 

HUE 

Returns the hue level. 

IMAGE BITSPERPEL 

Returns the number of bits per pixel for saving bit maps and images. 

IMAGE COMPRESSION 

Returns the compression type used for saving bit maps and images. 

IMAGE FILE FORMAT 

Returns the image file format. 

IMAGE PELFORMAT 

Returns the pel format for saving bit maps and images. 

IMAGE QUALITY 

Returns the still image quality level. 

MODE 

Returns OTHER. 

READY 

Returns TRUE. 

SATURATION 

Returns the saturation level. 

SHARPNESS 

Returns the sharpness level. 

TIME FORMAT 

Returns the time format. 

TRANSPARENT COLOR 

Returns the transparency color value, relative to the transparency type. Video displays through all pels of this color. 


M-Motion specific: Returns 3 (CLR_PINK). 

TRANSPARENT TYPE 

Returns the type of transparency supported (if any), such as RGB value or palette entry. 

M-Motion specific: Returns PALETTE. 

VERTICAL IMAGE EXTENT 

Returns the vertical (Y) source extent for the currently loaded image. 


WINDOW HANDLE 

Returns the window handle of the overlay video window in the low word of the return value. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (Video Overlay Command) - Syntax Diagram 


STATUS object BRIGHTNESS 

CONTRAST WAIT 

GREYSCALE NOTIFY 

HORIZONTAL IMAGE EXTENT 
HUE 

IMAGE BITSPERPEL 
IMAGE COMPRESSION 
IMAGE FILE FORMAT 
IMAGE PELFORMAT 
IMAGE QUALITY 
MODE 
READY 

SATURATION 
SHARPNESS 
TIME FORMAT 
TRANSPARENT COLOR 
TRANSPARENT TYPE 
VERTICAL IMAGE EXTENT 
WINDOW HANDLE 


Examples 
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UNFREEZE 


UNFREEZE (Video Overlay Command) - Example 


unfreeze videooverlay at 100 100 260 220 wait 


UNFREEZE (Video Overlay Command) - Purpose 


The UNFREEZE command stops updating the video buffer by the video source. Supported only if can freeze returns TRUE. (See the 
CAPABILITY command.) 


UNFREEZE (Video Overlay Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


UNFREEZE (Video Overlay Command) Keyword - AT rect 


AT rect 

Specifies a rectangle relative to the window origin in device coordinates. The rectangle array is specified as XI Y1 X2 Y2. The 
coordinates XI Y1 specify the lower-left corner and X2 Y2 specify the upper-right corner. Only the video in that subregion will be 
unfrozen. 


UNFREEZE (Video Overlay Command) Keyword - OUTSIDE 
rect 


OUTSIDE rect 

The area outside the specified rectangle is to be affected. 


UNFREEZE (Video Overlay Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


UNFREEZE (Video Overlay Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


UNFREEZE (Video Overlay Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


AT rect 

Specifies a rectangle relative to the window origin in device coordinates. The rectangle array is specified as XI Y1 X2 Y2. The 
coordinates XI Y1 specify the lower-left corner and X2 Y2 specify the upper-right corner. Only the video in that subregion will be 
unfrozen. 


OUTSIDE rect 

The area outside the specified rectangle is to be affected. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


UNFREEZE (Video Overlay Command) - Syntax Diagram 


UNFREEZE 


object 


AT rect 
OUTSIDE rect 


WAIT 

NOTIFY 


Examples 
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WHERE 


WHERE (Video Overlay Command) - Example 


where videooverlay source wait 


WHERE (Video Overlay Command) - Purpose 


The WHERE command returns the source and destination rectangles set by the PUT command and returns the size and position of the 
video window. 


WHERE (Video Overlay Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 



Filename 

Alias 


WHERE (Video Overlay Command) Keyword - SOURCE 


SOURCE 

Returns the currently set source clipping rectangle, in the format XI Y1 X2 Y2. 


WHERE (Video Overlay Command) Keyword - 
DESTINATION 


DESTINATION 

Returns a rectangle that describes where in the video window that video will be displayed in the format XI Y1 X2 Y2. The coordinates 
XI Y1 specify the lower-left corner and X2 Y2 specify the upper-right corner. 


WHERE (Video Overlay Command) Keyword - WINDOW 


WINDOW 

Returns the current window position and size relative to the parent window in the format XI Y1 X2 Y2. The coordinates XI Y1 specify 
the lower-left corner and X2 Y2 specify the upper-right corner. 


WHERE (Video Overlay Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


WHERE (Video Overlay Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


WHERE (Video Overlay Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 

SOURCE 

Returns the currently set source clipping rectangle, in the format XI Y1 X2 Y2. 

DESTINATION 

Returns a rectangle that describes where in the video window that video will be displayed in the format XI Y1 X2 Y2. The coordinates 
XI Y1 specify the lower-left corner and X2 Y2 specify the upper-right corner. 

WINDOW 

Returns the current window position and size relative to the parent window in the format XI Y1 X2 Y2. The coordinates XI Y1 specify 
the lower-left corner and X2 Y2 specify the upper-right corner. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


WHERE (Video Overlay Command) - Syntax Diagram 


WHERE object 

SOURCE 

DESTINATION 

WINDOW 


WAIT 

NOTIFY 


Examples 
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WINDOW 


WINDOW (Video Overlay Command) - Example 


window videooverlay handle default wait 


WINDOW (Video Overlay Command) - Purpose 


The WINDOW command controls the appearance of the video window. 


WINDOW (Video Overlay Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


WINDOW (Video Overlay Command) Keyword - HANDLE 
window handle 


HANDLE windowhandle 

Sets a new window in which to play the video image. If the old window was the default window created by the driver, it is hidden. 
Otherwise, the application is responsible for managing the old window. 


WINDOW (Video Overlay Command) Keyword - HANDLE 
DEFAULT 



HANDLE DEFAULT 

Indicates the driver should display video in the window automatically created by the driver. 


WINDOW (Video Overlay Command) Keyword - STATE 
ACTIVATE 


STATE ACTIVATE 

Activates the default video window if it is a frame window. This has no other effect on other windows. The frame window is made the 
topmost window. 


WINDOW (Video Overlay Command) Keyword - STATE 
DEACTIVATE 


STATE DEACTIVATE 

Deactivates the default video window if it is a state window. This has no effect on other windows. 


WINDOW (Video Overlay Command) Keyword - STATE HIDE 


STATE HIDE 

Hides the default video window. 


WINDOW (Video Overlay Command) Keyword - STATE 
MAXIMIZE 


STATE MAXIMIZE 

Maximizes the default video window. This indicator has no effect if the window is in a maximized state, and is also mutually exclusive 
with STATE MINIMIZE and STATE RESTORE. 


WINDOW (Video Overlay Command) Keyword - STATE 
MINIMIZE 


STATE MINIMIZE 



Minimizes the default video window. This indicator has no effect if the window is in a minimized state, and is also mutually exclusive 
with STATE MAXIMIZE and STATE RESTORE. 


WINDOW (Video Overlay Command) Keyword - STATE 
RESTORE 


STATE RESTORE 

Restores the default video window. This indicator has no effect if currently in a window and is mutually exclusive with STATE 
MAXIMIZE and STATE MINIMIZE. 


WINDOW (Video Overlay Command) Keyword - STATE 
SHOW 


STATE SHOW 

Shows the default video window. 


WINDOW (Video Overlay Command) Keyword - TEXT 
caption 


TEXT caption 

Specifies the text to display in the caption of the default video window. 


WINDOW (Video Overlay Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


WINDOW (Video Overlay Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


WINDOW (Video Overlay Command) - Keywords 


Note: The STATE and TEXT keywords will not affect an application-supplied alternate window. 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

HANDLE window handle 

Sets a new window in which to play the video image. If the old window was the default window created by the driver, it is hidden. 
Otherwise, the application is responsible for managing the old window. 

HANDLE DEFAULT 

Indicates the driver should display video in the window automatically created by the driver. 

STATE ACTIVATE 

Activates the default video window if it is a frame window. This has no other effect on other windows. The frame window is made the 
topmost window. 

STATE DEACTIVATE 

Deactivates the default video window if it is a state window. This has no effect on other windows. 

STATE HIDE 

Hides the default video window. 

STATE MAXIMIZE 

Maximizes the default video window. This indicator has no effect if the window is in a maximized state, and is also mutually exclusive 
with STATE MINIMIZE and STATE RESTORE. 

STATE MINIMIZE 

Minimizes the default video window. This indicator has no effect if the window is in a minimized state, and is also mutually exclusive 
with STATE MAXIMIZE and STATE RESTORE. 

STATE RESTORE 

Restores the default video window. This indicator has no effect if currently in a window and is mutually exclusive with STATE 
MAXIMIZE and STATE MINIMIZE. 

STATE SHOW 

Shows the default video window. 


TEXT caption 

Specifies the text to display in the caption of the default video window. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


WINDOW (Video Overlay Command) - Syntax Diagram 


WINDOW 


object 


HANDLE window_handle WAIT 

HANDLE DEFAULT NOTIFY 

STATE ACTIVATE 

STATE DEACTIVATE 

STATE HIDE 

STATE MAXIMIZE 

STATE MINIMIZE 

STATE RESTORE 

STATE SHOW 

TEXT caption 
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Waveform Audio Commands 


The waveform audio device supports the following device-type specific commands and extensions to the following basic and required 
commands: 


• CAPABILITY 

• CONNECTOR 

• COPY 
CUE 

• CUT 
DELETE 

• LOAD 
PASTE 

• RECORD 
REDO 

• SEEK 
SET 

• STATUS 
UNDO 


CAPABILITY 



CAPABILITY (Waveaudio Command) - Example 


capability waveaudio extended format bitspersample 16 
samplespersec 11025 tag PCM channels 2 mode play 


CAPABILITY (Waveaudio Command) - Purpose 


The CAPABILITY command requests additional information about the capabilities of waveform audio device driver. 


CAPABILITY (Waveaudio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CAPABILITY (Waveaudio Command) Keyword - CAN EJECT 


CAN EJECT 

Returns FALSE. Wave audio devices cannot eject the media. 


CAPABILITY (Waveaudio Command) Keyword - CAN PLAY 


CAN PLAY 

Returns TRUE. 


CAPABILITY (Waveaudio Command) Keyword - CAN 
RECORD 



CAN RECORD 

Returns TRUE if the current audio device supports recording. 


CAPABILITY (Waveaudio Command) Keyword - CAN SAVE 


CAN SAVE 

Returns TRUE if the wave audio device can save data. 


CAPABILITY (Waveaudio Command) Keyword - CAN 
SETVOLUME 


CAN SETVOLUME 

Returns TRUE if the device supports software control of volume level. 


CAPABILITY (Waveaudio Command) Keyword - 
COMPOUND DEVICE 


COMPOUND DEVICE 

Returns TRUE. Wave audio devices are compound devices. 


CAPABILITY (Waveaudio Command) Keyword - DEVICE 
TYPE 


DEVICE TYPE 

Returns waveaudio. 


CAPABILITY (Waveaudio Command) Keyword - EXTENDED 


EXTENDED 

Indicates that extended capabilities are to be queried. 



CAPABILITY (Waveaudio Command) Keyword - FORMAT 


FORMAT 

Indicates that waveaudio format will be queried. If FORMAT is specified, BITSPERSAMPLE, SAMPLESPERSEC, TAG, and 
CPIANNELS must also be specified. 


CAPABILITY (Waveaudio Command) Keyword - 
BITSPERSAMPLE integer 


BITSPERSAMPLE integer 

The integer indicates the number of bits in a waveaudio sample (typically 8 or 1 6). 


CAPABILITY (Waveaudio Command) Keyword - 
SAMPLESPERSEC integer 


SAMPLESPERSEC integer 

The integer indicates the number of samples per second the waveaudio will utilize. 


CAPABILITY (Waveaudio Command) Keyword - TAG type 


TAG type 

The type is a valid format tag which can be used with set (see the "SET object FORMAT TAG" command). 


CAPABILITY (Waveaudio Command) Keyword - CHANNELS 
integer 


CHANNELS integer 

Where integer indicates the number of channels (typically 1 or 2). 


CAPABILITY (Waveaudio Command) Keyword - MODE type 


MODE type 

Where type is either play or record. 


CAPABILITY (Waveaudio Command) Keyword - HAS AUDIO 


HAS AUDIO 

Returns TRUE. 


CAPABILITY (Waveaudio Command) Keyword - HAS VIDEO 


HAS VIDEO 

Returns FALSE. Wave audio devices do not support video. 


CAPABILITY (Waveaudio Command) Keyword - MESSAGE 
command 


MESSAGE command 

Returns TRUE if the device supports the command specified by command. The command can be any string command such as 
OPEN, PLAY, and so on. 


CAPABILITY (Waveaudio Command) Keyword - PREROLL 
TIME 


PREROLL TIME 

Returns 0, indicating the preroll time is not bounded. 


CAPABILITY (Waveaudio Command) Keyword - PREROLL 
TYPE 


PREROLL TYPE 



Returns the preroll characteristics of the device: Returns notified. 


CAPABILITY (Waveaudio Command) Keyword - USES FILES 

USES FILES 

Returns TRUE. Wave audio devices use files for operation. 


CAPABILITY (Waveaudio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


CAPABILITY (Waveaudio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete an MM_MC I NOTIFY message is sent to the application window procedure. 


CAPABILITY (Waveaudio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

CAN EJECT 

Returns FALSE. Wave audio devices cannot eject the media. 

CAN PLAY 

Returns TRUE. 

CAN RECORD 

Returns TRUE if the current audio device supports recording. 

CAN SAVE 

Returns TRUE if the wave audio device can save data. 

CAN SETVOLUME 

Returns TRUE if the device supports software control of volume level. 


COMPOUND DEVICE 

Returns TRUE. Wave audio devices are compound devices. 

DEVICE TYPE 

Returns waveaudio. 

EXTENDED 

Indicates that extended capabilities are to be queried. 

FORMAT 

Indicates that waveaudio format will be queried. If FORMAT is specified, BITSPERSAMPLE, SAMPLESPERSEC, 
TAG, and CPIANNELS must also be specified. 

BITSPERSAMPLE integer 

The integer indicates the number of bits in a waveaudio sample (typically 8 or 1 6). 

SAMPLESPERSEC integer 

The integer indicates the number of samples per second the waveaudio will utilize. 


TAG type 

The type is a valid format tag which can be used with set (see the "SET object FORMAT TAG" 
command). 

CHANNELS integer 

Where integer indicates the number of channels (typically 1 or 2). 


MODE type 

Where type is either play or record. 


HAS AUDIO 

Returns TRUE. 

HAS VIDEO 

Returns FALSE. Wave audio devices do not support video. 

MESSAGE command 

Returns TRUE if the device supports the command specified by command. The command can be any string command such as 
OPEN, PLAY, and so on. 

PREROLL TIME 

Returns 0, indicating the preroll time is not bounded. 

PREROLL TYPE 

Returns the preroll characteristics of the device: Returns notified. 

USES FILES 

Returns TRUE. Wave audio devices use files for operation. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete an MM_MCINOTIFY message is sent to the application window procedure. 


CAPABILITY (Waveaudio Command) - Syntax Diagram 


CAPABILITY object 


CAN EJECT 
CAN PLAY 
CAN RECORD 
CAN SAVE 


WAIT 

NOTIFY 


CAN SETVOLUME 
COMPOUND DEVICE 
DEVICE TYPE 


EXTENDED FORMAT BITSPERSAMPLE integer 

SAMPLESPERSEC integer 
TAG type 

CHANNELS integer 
MODE type 

HAS AUDIO 
HAS VIDEO 
MESSAGE command 
PREROLL TIME 
PREROLL TYPE 
USES FILES 


Examples 
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CONNECTOR 


CONNECTOR (Waveaudio Command) - Example 


connector waveaudio enable type line in wait 


CONNECTOR (Waveaudio Command) - Purpose 


The CONNECTOR command enables, disables, or queries the status of connector on a device. 


CONNECTOR (Waveaudio Command) Keyword - object 



object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


CONNECTOR (Waveaudio Command) Keyword - ENABLE 


ENABLE 

Enables information flow through the indicated connector. Use of this keyword requires that the NUMBER or TYPE keywords must 
also be specified. 


CONNECTOR (Waveaudio Command) Keyword - DISABLE 


DISABLE 

Disables information flow through the indicated connector. Use of this keyword requires that the NUMBER or TYPE keywords must 
also be specified. 


CONNECTOR (Waveaudio Command) Keyword - QUERY 


QUERY 

Queries the state of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled 
respectively. Use of this keyword requires that the NUMBER or TYPE keywords must also be specified. 


CONNECTOR (Waveaudio Command) Keyword - NUMBER 
connector number 


NUMBER connector number 

Indicates the connector number on which to perform the requested action. If this item is omitted, then the first connector is assumed. 
If the TYPE item is included, then the connector number is interpreted as a relative offset within the specified connector type. 


CONNECTOR (Waveaudio Command) Keyword - TYPE 



connector_type 


TYPE connector type 

Indicates the type of connector to which the requested action applies. The following connector types are directly supported by this 
device. 

wave stream 

Digital input or output for the audio amplifier/mixer. This connector is always enabled. 

The waveform audio device also recognizes the following connector types and will attempt to control the corresponding amp/mixer 
connector if the amp/mixer provides the support. 

line in 

The line input connector. This connector is usually attached to the line out connector of another device such as a 
tape player or other audio input source. 

microphone 

The microphone connector. This connector is usually attached to a microphone for live recording or voice 
annotation. 

line out 

The line output connector. This connector is usually attached to the line in connector of another device such as a 
tape recorder or other audio device. 

speakers 

The speakers connector. This connector is usually attached to a pair of external or internal speakers. 

headphones 

The headphones connector. This connector is usually attached to a pair of headphones. 


CONNECTOR (Waveaudio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CONNECTOR (Waveaudio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CONNECTOR (Waveaudio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 


Device type 


Device name 

Filename 

Alias 


ENABLE 

Enables information flow through the indicated connector. Use of this keyword requires that the NUMBER or TYPE keywords must 
also be specified. 

DISABLE 

Disables information flow through the indicated connector. Use of this keyword requires that the NUMBER or TYPE keywords must 
also be specified. 

QUERY 

Queries the state of the indicated connector. The return value will be either TRUE or FALSE to indicate enabled or disabled 
respectively. Use of this keyword requires that the NUMBER or TYPE keywords must also be specified. 

NUMBER connector number 

Indicates the connector number on which to perform the requested action. If this item is omitted, then the first connector is assumed. 

If the TYPE item is included, then the connector number is interpreted as a relative offset within the specified connector type. 

TYPE connector type 

Indicates the type of connector to which the requested action applies. The following connector types are directly supported by this 
device. 

wave stream 

Digital input or output for the audio amplifier/mixer. This connector is always enabled. 

The waveform audio device also recognizes the following connector types and will attempt to control the corresponding amp/mixer 
connector if the amp/mixer provides the support. 

line in 

The line input connector. This connector is usually attached to the line out connector of another device such as a 
tape player or other audio input source. 

microphone 

The microphone connector. This connector is usually attached to a microphone for live recording or voice 
annotation. 

line out 

The line output connector. This connector is usually attached to the line in connector of another device such as a 
tape recorder or other audio device. 

speakers 

The speakers connector. This connector is usually attached to a pair of external or internal speakers. 

headphones 

The headphones connector. This connector is usually attached to a pair of headphones. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


CONNECTOR (Waveaudio Command) - Syntax Diagram 


CONNECTOR object 


ENABLE 

DISABLE 

QUERY 


NUMBER connector_number 


TYPE connector_type 


WAIT 

NOTIFY 


Examples 
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COPY 


COPY (Waveaudio Command) - Example 


copy waveaudio from 1000 to 5000 


COPY (Waveaudio Command) - Purpose 


The COPY command copies information from a file into the clipboard. 


COPY (Waveaudio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 



COPY (Waveaudio Command) Keyword - FROM pos 


FROM pos 

The position to start copying. If FROM is omitted, the copy starts from the current position. If TO is omitted, the end of file is assumed. 
The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not specified. 


COPY (Waveaudio Command) Keyword - TO pos 


TO pos 

The position to stop copying. If TO is omitted, the end of file is assumed. The position of the media will either be the from position if 
FROM is specified, or the previous position if FROM is not specified. 


COPY (Waveaudio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


COPY (Waveaudio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


COPY (Waveaudio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 

FROM pos 

The position to start copying. If FROM is omitted, the copy starts from the current position. If TO is omitted, the end of file is assumed. 
The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not specified. 


TO pos 

The position to stop copying. If TO is omitted, the end of file is assumed. The position of the media will either be the from position if 
FROM is specified, or the previous position if FROM is not specified. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


COPY (Waveaudio Command) - Syntax Diagram 


COPY object 


FROM pos 
TO pos 


WAIT 

NOTIFY 


Examples 
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CUE 


CUE (Waveaudio Command) - Example 


cue waveaudio input wait 



CUE (Waveaudio Command) - Purpose 


The CUE command prepares for playback or recording. The CUE command does not have to be issued prior to playback or recording. 
However, depending on the device, it can reduce the delay associated with the PLAY or RECORD command. 

The CUE command is not related to the SETCUEPOINT command. 


CUE (Waveaudio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


CUE (Waveaudio Command) Keyword - INPUT 


INPUT 

Prepares the input for recording. 


CUE (Waveaudio Command) Keyword - OUTPUT 


OUTPUT 

Prepares the output for playback. This is the default. 


CUE (Waveaudio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CUE (Waveaudio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CUE (Waveaudio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


INPUT 

Prepares the input for recording. 

OUTPUT 

Prepares the output for playback. This is the default. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


CUE (Waveaudio Command) - Syntax Diagram 


CUE object 


INPUT 

OUTPUT 


WAIT 

NOTIFY 


Examples 
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CUT 


CUT (Waveaudio Command) - Example 


cut waveaudio from 1000 to 4000 wait 


CUT (Waveaudio Command) - Purpose 


The CUT command cuts removes the specified range and places the data in the clipboard. 


CUT (Waveaudio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


CUT (Waveaudio Command) Keyword - FROM pos 


FROM pos 

The position to start cutting. If FROM is omitted, the cut starts from the current position. If TO is omitted, the end of file is assumed. 
The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not specified. 


CUT (Waveaudio Command) Keyword - TO pos 


TO pos 

The position to stop cutting. If FROM is omitted, the cut starts from the current position. If TO is omitted, the end of file is assumed. 
The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not specified. 


CUT (Waveaudio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


CUT (Waveaudio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


CUT (Waveaudio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

FROM pos 

The position to start cutting. If FROM is omitted, the cut starts from the current position. If TO is omitted, the end of file is assumed. 
The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not specified. 

TO pos 

The position to stop cutting. If FROM is omitted, the cut starts from the current position. If TO is omitted, the end of file is assumed. 
The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not specified. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


CUT (Waveaudio Command) - Syntax Diagram 


CUT 


object 


FROM pos 
TO pos 


WAIT 

NOTIFY 


Examples 
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DELETE 


DELETE (Waveaudio Command) - Example 


delete waveaudio from 1000 to 4000 wait 


DELETE (Waveaudio Command) - Purpose 


The DELETE command deletes information from a file. 


DELETE (Waveaudio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 


Device type 



Device name 

Filename 

Alias 


DELETE (Waveaudio Command) Keyword - FROM pos 


FROM pos 

The position to start deleting. If FROM is omitted, the delete starts from the current position. If TO is omitted, the end of file is 
assumed. The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not 
specified. 


DELETE (Waveaudio Command) Keyword - TO pos 


TO pos 

The position to stop deleting. If FROM is omitted, the delete starts from the current position. If TO is omitted, the end of file is 
assumed. The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not 
specified. 


DELETE (Waveaudio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


DELETE (Waveaudio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


DELETE (Waveaudio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 


Device type 


Device name 

Filename 

Alias 


FROM pos 

The position to start deleting. If FROM is omitted, the delete starts from the current position. If TO is omitted, the end of file is 
assumed. The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not 
specified. 

TO pos 

The position to stop deleting. If FROM is omitted, the delete starts from the current position. If TO is omitted, the end of file is 
assumed. The position of the media will either be the from position if FROM is specified, or the previous position if FROM is not 
specified. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


DELETE (Waveaudio Command) - Syntax Diagram 


DELETE object 


FROM pos 
TO pos 


WAIT 

NOTIFY 


Examples 
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LOAD 



LOAD (Waveaudio Command) - Example 

load waveaudio bells.wav wait 


LOAD (Waveaudio Command) - Purpose 


The LOAD command loads a new device element (file) into an already open device context. 


LOAD (Waveaudio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


LOAD (Waveaudio Command) Keyword - filename 


filename 

The name of the file to load. Optional if OPEN is specified. 


LOAD (Waveaudio Command) Keyword - READONLY 


READONLY 

The system will open the file in a read-only mode to prevent any inadvertent modifications to the file. The waveaudio driver might also 
be able to improve load and run time performance as no modifications will be allowed. This flag can only be specified in conjunction 
with a file element. Specifying the READONLY keyword will disable support for the SAVE, RECORD, CUT, DELETE, and PASTE 
commands. 


LOAD (Waveaudio Command) Keyword - NEW 



NEW 


A temporary element is created for subsequent use with MCI_RECORD, MCI_PLAY, and other commands. The temporary file can 
be made permanent by providing a name using the MCI_SAVE message. 


LOAD (Waveaudio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


LOAD (Waveaudio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


LOAD (Waveaudio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

filename 

The name of the file to load. Optional if OPEN is specified. 

READONLY 

The system will open the file in a read-only mode to prevent any inadvertent modifications to the file. The 
waveaudio driver might also be able to improve load and run time performance as no modifications will be allowed. 
This flag can only be specified in conjunction with a file element. Specifying the READONLY keyword will disable 
support for the SAVE, RECORD, CUT, DELETE, and PASTE commands. 


NEW 

A temporary element is created for subsequent use with MCI_RECORD, MCI_PLAY, and other commands. The temporary file can 
be made permanent by providing a name using the MCI_SAVE message. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


LOAD (Waveaudio Command) - Syntax Diagram 


LOAD 


object 


filename 


NEW 


READONLY 


WAIT 

NOTIFY 


Examples 
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PASTE 


PASTE (Waveaudio Command) - Example 


paste waveaudio from 1000 to 4000 wait 


PASTE (Waveaudio Command) - Purpose 


The PASTE command pastes information from the clipboard into a file. The media position after a paste operation is at the end of the pasted 
data. 


PASTE (Waveaudio Command) Keyword - object 



object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


PASTE (Waveaudio Command) Keyword - FROM pos 


FROM pos 

The position to start pasting. If FROM is omitted, the paste starts at the current position. 


PASTE (Waveaudio Command) Keyword - TO pos 


TO pos 

The position to stop pasting. The pasted data rep/aces data from the FROM position (or the current position if FROM is not specified) 
to the TO position. 

If TO is omitted, the end of file is assumed and the pasted data is inserted starting at the FROM position (or the current position if 
FROM is not specified). 


PASTE (Waveaudio Command) Keyword - CONVERT 


CONVERT 

Converts data in the clipboard to the current file format. 


PASTE (Waveaudio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


PASTE (Waveaudio Command) Keyword - NOTIFY 



NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


PASTE (Waveaudio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 

FROM pos 

The position to start pasting. If FROM is omitted, the paste starts at the current position. 

TO pos 

The position to stop pasting. The pasted data rep/aces data from the FROM position (or the current position if FROM is not specified) 
to the TO position. 

If TO is omitted, the end of file is assumed and the pasted data is inserted starting at the FROM position (or the current position if 
FROM is not specified). 

CONVERT 

Converts data in the clipboard to the current file format. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


PASTE (Waveaudio Command) - Syntax Diagram 


PASTE object 


FROM pos 

CONVERT 

TO pos 



WAIT 

NOTIFY 


Examples 
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RECORD 


RECORD (Waveaudio Command) - Example 

record waveaudio to 1000 overwrite wait 


RECORD (Waveaudio Command) - Purpose 


The RECORD command start recording audio. Recording does not overwrite existing data. New data is inserted at the current position. All 
data recorded after a file is opened is discarded if the file is closed without saving the data. 


RECORD (Waveaudio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


RECORD (Waveaudio Command) Keyword - FROM pos 


FROM pos 

The position to start recording. If FROM is omitted, the device starts recording at the current position; if TO is omitted, the device 
records until a STOP or PAUSE command is received. 


RECORD (Waveaudio Command) Keyword - TO pos 


TO pos 

The position to stop recording. If FROM is omitted, the device starts recording at the current position; if TO is omitted, the device 
records until a STOP or PAUSE command is received. 


RECORD (Waveaudio Command) Keyword - INSERT 


INSERT 

New data is added to the device element. 


RECORD (Waveaudio Command) Keyword - OVERWRITE 


OVERWRITE 

New data will replace data in the device element. 


RECORD (Waveaudio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


RECORD (Waveaudio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


RECORD (Waveaudio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

FROM pos 

The position to start recording. If FROM is omitted, the device starts recording at the current position; if TO is omitted, the device 
records until a STOP or PAUSE command is received. 

TO pos 

The position to stop recording. If FROM is omitted, the device starts recording at the current position; if TO is omitted, the device 
records until a STOP or PAUSE command is received. 

INSERT 

New data is added to the device element. 

OVERWRITE 

New data will replace data in the device element. 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


RECORD (Waveaudio Command) - Syntax Diagram 


RECORD object 


FROM pos 
TO pos 


INSERT 

OVERWRITE 


WAIT 

NOTIFY 


Examples 


RECORD (Waveaudio Command) - Remarks 


This command requires that a device element be loaded prior to recording. See the LOAD command for more information. 


RECORD (Waveaudio Command) - Topics 
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REDO 


REDO (Waveaudio Command) - Example 

redo waveaudio wait 


REDO (Waveaudio Command) - Purpose 


The REDO command redoes the last editing action (cut, paste, or delete) which was undone with the UNDO command. REDO should 
immediately follow UNDO; otherwise, editing actions performed after UNDO (and before a corresponding REDO) will be lost when the 
REDO command is issued. The position of the media after a redo operation is 0. 

Multiple REDO operations are permitted, corresponding to the number of editing operations that have been previously undone with the 
UNDO command. 


REDO (Waveaudio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


REDO (Waveaudio Command) Keyword - WAIT 


WAIT 


The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


REDO (Waveaudio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


REDO (Waveaudio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


REDO (Waveaudio Command) - Syntax Diagram 


REDO object 


WAIT 

NOTIFY 


Examples 
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SEEK 


SEEK (Waveaudio Command) - Example 


seek waveaudio to start wait 


SEEK (Waveaudio Command) - Purpose 


The SEEK command seeks finds the specified location in the file. 


SEEK (Waveaudio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

■ Filename 

• Alias 


SEEK (Waveaudio Command) Keyword - TO pos 


TO pos 

Specifies the final position for the seek. 


SEEK (Waveaudio Command) Keyword - TO START 


TO START 

Seeks to the start of the file. 


SEEK (Waveaudio Command) Keyword - TO END 


TO END 

Seeks to the end of the file. 


SEEK (Waveaudio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SEEK (Waveaudio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


SEEK (Waveaudio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


TO pos 

Specifies the final position for the seek. 

TO START 

Seeks to the start of the file. 

TO END 

Seeks to the end of the file. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


NOTIFY 



The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


SEEK (Waveaudio Command) - Syntax Diagram 


SEEK object 


TO pos 
TO START 
TO END 


WAIT 

NOTIFY 


Examples 


SEEK (Waveaudio Command) - Topics 


Select an item: 

Purpose 

Syntax Diagram 

Keywords 

Example 

Glossary 


SET 


SET (Waveaudio Command) - Example 


set waveaudio channels 2 wait 


SET (Waveaudio Command) - Purpose 


The SET command sets the various control and attribute items. 


SET (Waveaudio Command) Keyword - object 



object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


SET (Waveaudio Command) Keyword - AUDIO 


AUDIO 

Specifies the audio attributes of the device context determined by the ALL, LEFT, RIGFIT, OVER and VOLUME keywords. 


SET (Waveaudio Command) Keyword - ALL 


ALL 

Applies to both or all of the channels (default). 
Specify ON or OFF with the ALL keyword. 


SET (Waveaudio Command) Keyword - ON 


ON 

Enables audio. 


SET (Waveaudio Command) Keyword - OFF 


OFF 

Disables audio. 


SET (Waveaudio Command) Keyword - LEFT 


LEFT 



Applies to the left channel. 

Specify ON or OFF with the LEFT keyword. 


SET (Waveaudio Command) Keyword - ON 


ON 

Enables audio to the left channel. 


SET (Waveaudio Command) Keyword - OFF 


OFF 

Disables audio to the left channel. 


SET (Waveaudio Command) Keyword - RIGFIT 


RIGHT 

Applies to the right channel. 

Specify ON or OFF with the RIGFIT keyword. 


SET (Waveaudio Command) Keyword - ON 


ON 

Enables audio to the right channel. 


SET (Waveaudio Command) Keyword - OFF 


OFF 

Disables audio to the right channel. 


SET (Waveaudio Command) Keyword - OVER milliseconds 



OVER milliseconds 

Applies the change over the specified time period (fade). 


SET (Waveaudio Command) Keyword - VOLUME percentage 

VOLUME percentage 

Sets the volume level. 


SET (Waveaudio Command) Keyword - BITSPERSAMPLE 
integer 


BITSPERSAMPLE integer 

The number of bits per sample to be played or recorded. The file is saved in this format. 


SET (Waveaudio Command) Keyword - BYTESPERSEC 
integer 


BYTESPERSEC integer 

The average number of bytes per second to be played or recorded. The file is saved in this format. 


SET (Waveaudio Command) Keyword - CHANNELS integer 


CHANNELS integer 

The channel count for playing and recording. The file is saved in this format. 


SET (Waveaudio Command) Keyword - FORMAT TAG tag 


FORMAT TAG tag 

The format type for playing and recording. The file is saved in this format. If the waveform format is being changed then the SET 
command should be sent first with the FORMAT TAG keyword specified as the driver might need to change the other settings to be 
compatible with the new waveform format. After setting the waveform format, the other parameters can be set as necessary within 



the currently selected waveform format. An error will be returned if the requested change results in an unsupported configuration. 

An application can use the STATUS message to see if any of the other settings were changed to maintain a valid configuration. The 
following tag values are defined: 


pern 

The format type of PCM (pulse code modulation) for playing and recording. The file is saved in this format. 

avc adpem 

The IBM AVC ADPCM (adaptive differential pulse code modulation) format type for playing and recording. The 
file is saved in this format. 

microsoft adpem 

The Microsoft ADPCM format type for playing and recording. The file is saved in this format. 

evsd 

The IBM Speech Viewer format type for playing and recording. The file is saved in this format. 

alaw 

The CCITT A-Law format type for playing and recording. The file is saved in this format. 

mulaw 

The CCITT MuLaw format type for playing and recording. The file is saved in this format. 

ibm alaw 

The IBM A-Law format type for playing and recording. This format type is the same as CCITT A-Law. 

ibm mulaw 

The IBM A-Law format type for playing and recording. This format type is the same as CCITT Mulaw. 

ibm adpem 

The IBM ADPCM format type for playing and recording. The file is saved in this format. 

oki adpem 

The OKI ADPCM format type for playing and recording. The file is saved in this format. 

dvi adpem 

The DVI ADPCM format type for playing and recording. The file is saved in this format. 

ct adpem 

The format type of Creative Labs ADPCM for playing and recording. The file is saved in this format. 

digistd 

The IBM Digispeech standard format type for playing and recording. The file is saved in this format. 

digifix 

The IBM Digispeech fixed format type for playing and recording. The file is saved in this format. 


SET (Waveaudio Command) Keyword - SAMPLESPERSEC 
integer 

SAMPLESPERSEC integer 

The sample rate for playing and recording. The file is saved in this format. 


SET (Waveaudio Command) Keyword - TIME FORMAT 
BYTES 


TIME FORMAT BYTES 

Sets the time format to bytes. All position information is specified as bytes following this command. 


SET (Waveaudio Command) Keyword - TIME FORMAT 
MILLISECONDS 


TIME FORMAT MILLISECONDS 

Sets the time format to milliseconds. All position information is specified as milliseconds following this command. You can abbreviate 
milliseconds as ms. 


SET (Waveaudio Command) Keyword - TIME FORMAT 
MMTIME 


TIME FORMAT MMTIME 

Set the time format to MMTIME. 


SET (Waveaudio Command) Keyword - TIME FORMAT 
SAMPLES 


TIME FORMAT SAMPLES 

Sets the time format to samples. All position information is specified as samples following this command. 


SET (Waveaudio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


SET (Waveaudio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


SET (Waveaudio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

AUDIO 

Specifies the audio attributes of the device context determined by the ALL, LEFT, RIGFIT, OVER and VOLUME keywords. 

ALL 

Applies to both or all of the channels (default). 

Specify ON or OFF with the ALL keyword. 

ON 

Enables audio. 

OFF 

Disables audio. 

LEFT 

Applies to the left channel. 

Specify ON or OFF with the LEFT keyword. 

ON 

Enables audio to the left channel. 

OFF 

Disables audio to the left channel. 


RIGHT 


Applies to the right channel. 

Specify ON or OFF with the RIGFIT keyword. 


ON 

OFF 


Enables audio to the right channel. 
Disables audio to the right channel. 


OVER milliseconds 

Applies the change over the specified time period (fade). 

VOLUME percentage 

Sets the volume level. 

BITSPERSAMPLE integer 

The number of bits per sample to be played or recorded. The file is saved in this format. 

BYTESPERSEC integer 

The average number of bytes per second to be played or recorded. The file is saved in this format. 

CHANNELS integer 

The channel count for playing and recording. The file is saved in this format. 

FORMAT TAG tag 

The format type for playing and recording. The file is saved in this format. If the waveform format is being changed then the SET 
command should be sent first with the FORMAT TAG keyword specified as the driver might need to change the other settings to be 



compatible with the new waveform format. After setting the waveform format, the other parameters can be set as necessary within 
the currently selected waveform format. An error will be returned if the requested change results in an unsupported configuration. 

An application can use the STATUS message to see if any of the other settings were changed to maintain a valid configuration. The 
following tag values are defined: 

pern 

The format type of PCM (pulse code modulation) for playing and recording. The file is saved in this format. 

avc adpem 

The IBM AVC ADPCM (adaptive differential pulse code modulation) format type for playing and recording. The 
file is saved in this format. 

microsoft adpem 

The Microsoft ADPCM format type for playing and recording. The file is saved in this format. 

evsd 

The IBM Speech Viewer format type for playing and recording. The file is saved in this format. 

alaw 

The CCITT A-Law format type for playing and recording. The file is saved in this format. 

mulaw 

The CCITT MuLaw format type for playing and recording. The file is saved in this format. 

ibm alaw 

The IBM A-Law format type for playing and recording. This format type is the same as CCITT A-Law. 

ibm mulaw 

The IBM A-Law format type for playing and recording. This format type is the same as CCITT Mulaw. 

ibm adpem 

The IBM ADPCM format type for playing and recording. The file is saved in this format. 

oki adpem 

The OKI ADPCM format type for playing and recording. The file is saved in this format. 

dvi adpem 

The DVI ADPCM format type for playing and recording. The file is saved in this format. 

ct adpem 

The format type of Creative Labs ADPCM for playing and recording. The file is saved in this format. 

digistd 

The IBM Digispeech standard format type for playing and recording. The file is saved in this format. 

digifix 

The IBM Digispeech fixed format type for playing and recording. The file is saved in this format. 

SAMPLESPERSEC integer 

The sample rate for playing and recording. The file is saved in this format. 

TIME FORMAT BYTES 

Sets the time format to bytes. All position information is specified as bytes following this command. 

TIME FORMAT MILLISECONDS 

Sets the time format to milliseconds. All position information is specified as milliseconds following this command. You can abbreviate 
milliseconds as ms. 

TIME FORMAT MMTIME 

Set the time format to MMTIME. 

TIME FORMAT SAMPLES 

Sets the time format to samples. All position information is specified as samples following this command. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MCINOTIFY message is sent to the application window procedure. 


SET (Waveaudio Command) - Syntax Diagram 


SET object AUDIO 


ALL 

ON 


OFF 

LEFT 

ON 


OFF 

RIGHT 

ON 


OFF 


OVER milliseconds 
VOLUME percentage 
BITSPERSAMPLE integer 
BYTESPERSEC integer 
CHANNELS integer 
FORMAT TAG tag 
SAMPLESPERSEC integer 
TIME FORMAT BYTES 
TIME FORMAT MILLISECONDS 
TIME FORMAT MMTIME 
TIME FORMAT SAMPLES 


WAIT 

NOTIFY 


Examples 
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STATUS 


STATUS (Waveaudio Command) - Example 


status waveaudio mode wait 



STATUS (Waveaudio Command) - Purpose 


The STATUS command obtains status information for the device. 


STATUS (Waveaudio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


STATUS (Waveaudio Command) Keyword - ALIGNMENT 


ALIGNMENT 

Returns the block alignment of data in bytes. 


STATUS (Waveaudio Command) Keyword - 
BITSPERSAMPLE 


BITSPERSAMPLE 

Returns the bits per sample. 


STATUS (Waveaudio Command) Keyword - BYTESPERSEC 


BYTESPERSEC 

Returns the average number of bytes per second played or recorded. 


STATUS (Waveaudio Command) Keyword - CHANNELS 



CHANNELS 

Returns the number of channels set (1 for monaural, 2 for stereo). 


STATUS (Waveaudio Command) Keyword - CURRENT 
TRACK 


CURRENT TRACK 

Returns 1 for the current track. 


STATUS (Waveaudio Command) Keyword - FORMAT TAG 


FORMAT TAG 

Returns the format tag. 


STATUS (Waveaudio Command) Keyword - LENGTFI 


LENGTH 

Returns the total length of the waveform. 


STATUS (Waveaudio Command) Keyword - LENGTH TRACK 
track number 


LENGTH TRACK track_number 

Returns the length of the specified track. 


STATUS (Waveaudio Command) Keyword - LEVEL 


LEVEL 

Returns the current audio sample value. 


STATUS (Waveaudio Command) Keyword - MEDIA 



PRESENT 


MEDIA PRESENT 

Returns MCI_TRUE. 


STATUS (Waveaudio Command) Keyword - MODE 


MODE 

Returns the current mode of the device: not ready, stopped, playing, seeking, recording, paused, or other. 


STATUS (Waveaudio Command) Keyword - NUMBER OF 
TRACKS 


NUMBER OF TRACKS 

Returns the number of tracks. 


STATUS (Waveaudio Command) Keyword - POSITION 


POSITION 

Returns the current position. 


STATUS (Waveaudio Command) Keyword - POSITION 
TRACK track number 


POSITION TRACK track_number 

Returns the position of the track specified by track_number. 


STATUS (Waveaudio Command) Keyword - READY 


READY 

Returns MCI_TRUE if the device is ready. 



STATUS (Waveaudio Command) Keyword - 
SAMPLESPERSEC 


SAMPLESPERSEC 

Returns the number of samples per second played or recorded. 


STATUS (Waveaudio Command) Keyword - TIME FORMAT 


TIME FORMAT 

Returns the time format. 


STATUS (Waveaudio Command) Keyword - VOLUME 


VOLUME 

Returns the current volume setting. The volume is returned as a string in the format /eftright where /eft and right are percentages of 
the maximum achievable effect for the left and right channels respectively. Leading zeros are suppressed for the volume level in each 
channel. 


STATUS (Waveaudio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 


STATUS (Waveaudio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (Waveaudio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 

ALIGNMENT 

Returns the block alignment of data in bytes. 

BITSPERSAMPLE 

Returns the bits per sample. 

BYTESPERSEC 

Returns the average number of bytes per second played or recorded. 

CHANNELS 

Returns the number of channels set (1 for monaural, 2 for stereo). 

CURRENT TRACK 

Returns 1 for the current track. 

FORMAT TAG 

Returns the format tag. 

LENGTH 

Returns the total length of the waveform. 

LENGTH TRACK track_number 

Returns the length of the specified track. 

LEVEL 

Returns the current audio sample value. 

MEDIA PRESENT 

Returns MCI_TRUE. 

MODE 

Returns the current mode of the device: not ready, stopped, playing, seeking, recording, paused, or other. 

NUMBER OF TRACKS 

Returns the number of tracks. 

POSITION 

Returns the current position. 

POSITION TRACK track_number 

Returns the position of the track specified by track_number. 

READY 

Returns MCI_TRUE if the device is ready. 

SAMPLESPERSEC 

Returns the number of samples per second played or recorded. 

TIME FORMAT 

Returns the time format. 

VOLUME 

Returns the current volume setting. The volume is returned as a string in the format /eft.right where /eft and right are percentages of 
the maximum achievable effect for the left and right channels respectively. Leading zeros are suppressed for the volume level in each 
channel. 

WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. The WAIT keyword must be specified in order to receive return string information. 

NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 



is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


STATUS (Waveaudio Command) - Syntax Diagram 


STATUS object 


ALIGNMENT 

BITSPERSAMPLE WAIT 

BYTESPERSEC NOTIFY 

CHANNELS 

CURRENT TRACK 

FORMAT TAG 

LENGTH 

LENGTH TRACK track_number 
LEVEL 

MEDIA PRESENT 

MODE 

POSITION 

POSITION TRACK track_number 

NUMBER OF TRACKS 

READY 

SAMPLESPERSEC 
TIME FORMAT 
VOLUME 
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UNDO 


UNDO (Waveaudio Command) - Example 


undo waveaudio wait 



UNDO (Waveaudio Command) - Purpose 


The UNDO command undoes the last change to a file. The position of the media after the undo is 0. 


UNDO (Waveaudio Command) Keyword - object 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

• Device name 

• Filename 

• Alias 


UNDO (Waveaudio Command) Keyword - WAIT 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


UNDO (Waveaudio Command) Keyword - NOTIFY 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


UNDO (Waveaudio Command) - Keywords 


object 

Object associated with this media control interface command. The object can be one of the following: 

• Device type 

■ Device name 

• Filename 

• Alias 


WAIT 

The command is executed synchronously. The function waits until the requested action is complete before returning to the 
application. 


NOTIFY 

The command is executed asynchronously, allowing control to be returned immediately to the application. When the requested action 
is complete, an MM_MC I NOTIFY message is sent to the application window procedure. 


UNDO (Waveaudio Command) - Syntax Diagram 


UNDO object 


WAIT 

NOTIFY 


Examples 
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Memory Playlist Commands 


A memory playlist is a data structure in your application. It contains an array of simple, machine-like instructions, or commands, each of 
which has a fixed format consisting of a 32-bit operation code and three 32-bit operands. 

Using playlist instructions, you can play audio objects in succession from one or more memory buffers. Instructions include branching to and 
returning from subroutines within the playlist. In addition, the playlist can be modified dynamically by the application while it is being played. 

The MCI_OPEN_PLAYLIST flag is specified for the MCI_OPEN command message to indicate that the pszE/ement/Vame field in the 
MCI_OPEN_PARMS data structure is a pointer to a memory playlist. The following table lists and describes the playlist instructions. 


Command Description 

BRANCH_OPERATION Transfers control to another instruction 

in the playlist. 


CALL_OPERATION Transfers control to the instruction 

specified in Operand 2 , saving the 
number of the instruction following the 
CALL_OPERATION for use on a 
RETURN_OPERATION . 


CUEPOINT_OPERATION Causes a cue-point data record to be 
entered into the data stream. 


DATA_OPERATION Specifies a data buffer to be played 



from or recorded into. 


EXIT_OPERATION 

Indicates the end of the playlist. 

LOOP_OPERATION 

Controls iteration in a playlist. 

ME S S AGE_OP ERAT I ON 

Returns a message to the application 
during playlist processing. 
MESSAGE_OPERATION statements can be used 
by the application to trace specific 
points during the execution of the 
playlist processor. 

NOP_OPERATION 

Used as a placeholder. 

RE T U RN_OP E RAT I ON 

Transfers control to the playlist 
instruction following the most recently 
executed CALL_OPERATION . 

S EMP 0 S T_OP E RAT I ON 

Causes the playlist processor to post an 
event semaphore. The playlist processor 
will call DosWaitEventSem. 

S EMWA I T_OP E RAT I ON 

Causes the playlist processor to wait on 
a semaphore. The playlist processor will 
call DosWaitEventSem. 

Playlist Instructions 



The commands and their descriptions (including operand information) follow: 

BRANCHOPERATION 

Transfers control to another instruction in the playlist. 


Operand 1 

Ignored. 

Operand 2 

The absolute instruction number in the playlist to which control is being transferred. 
Because the playlist is defined as an array of structures (instruction, operation, and 
operand values) its first instruction is referenced as array element, index 0. Therefore, 
the first instruction in the list is 0, the second instruction is 1 , and so on. 

Operand 3 

Ignored. 


Branching out of a subroutine is not prohibited; however, it is not recommended because an unused return address is left on the 
stack maintained by the playlist processor. 

An application can enable or disable a BRANCHJOPERATION by exchanging it with a NOP_OPERATION. Operands for a 
NOP_OPERATION are ignored. 

CALLOPERATION 

Transfers control to the absolute instruction number specified in Operand 2, saving the number of the instruction following the CALL 
for use on a RETURN instruction. 

CALL instructions may be nested up to 20 levels. 


Operand 1 

Ignored. 

Operand 2 

Absolute instruction number in the playlist to which control is being transferred. 

Operand 3 

Ignored. 


CUEPOINTOPERATION 

Causes a cue-point data record to be entered into the data stream. Note that the cue point is relative to the DATAJOPERATION that 
follows it. 


Operand 1 

User-defined parameter to be returned as the low word of MsgParaml in the 


MM_MCICUEPOINT message. 

Operand 2 

Offset in MMTIME units for the actual time the CUEPOINT message should be 
generated. 


Operand 3 


Ignored. 


The MM_MCICUEPOINT message is returned to the application as soon as possible after the cue-point data record is encountered in 
the data stream. The message is sent to the window handle specified when the device was originally opened. 

Note: The CUEPOINT instruction is ignored when used in a recording operation. 

DATAOPERATION 

Specifies a data buffer to be played from or recorded into. 

Operand 1 long pointer to a buffer in the application. 

Operand 2 Length of the buffer pointed to by Operand 1 . 

Operand 3 Current position in the buffer. This operand is updated by the system during a 

recording or playback operation. For a playback operation, it is the number of bytes 
that have been sent to the output device handler. For a recording operation, it is the 
number of bytes that have been placed into a user buffer. 

The current position in the buffer is particularly important after a recording operation, 
because this field contains the number of bytes of recorded data. The remaining bytes 
in the buffer are not valid. 

The buffer indicated by the DATA instruction must only contain the raw data bytes from the device and cannot include any header 
information. For example, a buffer for a sequencer device can contain only MIDI multibyte messages, as defined by the International 
MIDI Association. Therefore, the precise meaning or format of the data is dependent on the current settings of the media device. For 
example, a wave audio data element is assumed to have the format PCM or ADPCM, number of bits per sample, and so on, that is 
indicated by the settings of the audio device. 

The address range of a DATA statement cannot overlap the address range of any another DATA statement. Flowever, the same 
DATA statement can be repeated. 

EXITOPERATION 

Indicates the end of the playlist. 

Operand 1 
Operand 2 
Operand 3 

LOOP_OPERATION 

Controls iteration in a playlist. It is the responsibility of the application to initialize the current iteration. The current iteration is reset to 
zero following loop termination. 

Operand 1 Number of times the loop is to be executed. 

Operand 2 Target instruction to branch to, when the loop condition fails. 

Operand 3 Current iteration. 

The last instruction in a loop is a branch back to the LOOP_OPERATION. The operation of the LOOP_OPERATION instruction is as 
follows: 

1 . If Operand 3 is less than Operand 1 , control is transferred to the playlist instruction following the LOOP instruction, and 
the iteration count in Operand 3 is incremented. 

2. Otherwise, the iteration count is reset to zero and control is passed to the instruction specified in Operand 2. 

Typically, the application sets the iteration count to zero when the playlist is passed to the device, but this is not required. The loop 
instruction merely compares the loop count with the iteration count. If the iteration count is set to a value other than zero when the 
playlist is passed in, it is as if the loop has been executed that number of times. Also, if a playback operation is stopped, and then the 
same playlist is loaded again, the loop iteration count is not initialized by the playlist processor. 

It is the application's responsibility to see that iteration count values are what is required when switching from play to record, record to 
play, and when changing settings for the data (for example, b/tspersamp/e , samp/espersec , and so on) with the set command. 

These commands cause the playlist stream to be destroyed and re-created, and the playlist to be reassociated as a new playlist with 
the playlist processor. 

MESSAGEOPERATION 

Returns a message to the application during playlist processing. 

Operand 1 Ignored. 

Operand 2 ULONG that is returned to the application in the MM_MCIPLAYLISTMESSAGE 

message MsgParam2. 


Ignored. 

Ignored. 

Ignored. 


Operand 3 


Ignored. 


Each time the playlist processor encounters a MESSAGE instruction, MM_MCIPLAYLISTMESSAGE is returned to the application. 
MESSAGE instructions can be used by the application to trace specific points during the execution of the playlist processor. 

Note: This function is not intended to be used for timing of data production or consumption identified by previously interpreted 
instructions. 

NOP_OPERATION 

Used as a placeholder. 

Operand 1 
Operand 2 
Operand 3 

RETURNOPERATION 

Transfers control to the playlist instruction following the most recently executed CALL instruction. 

Operand 1 Ignored. 

Operand 2 Ignored. 

Operand 3 Ignored. 

SEMPOSTOPERATION 

Causes the playlist processor to post an event semaphore. The playlist processor will call DosWaitEventSem. 

Operand 1 Contains the semaphore to post. 

Operand 2 Ignored. 

Operand 3 Ignored. 

SEMWAITOPERATION 

Causes the playlist processor to wait on a semaphore. The playlist processor will call DosWaitEventSem. 

Contains the semaphore to perform the wait on. 

Amount of time the semaphore should wait. 

Boolean value indicating whether or not the semaphore should be cleared before 
waiting. 


Graphic Button Control 


Operand 1 
Operand 2 
Operand 3 


Ignored. 

Ignored. 

Ignored. 


This section describes graphic button styles and control messages. Graphic buttons are different from other types of push buttons in that 
they have graphic, two-state, and animation capabilities. Using graphic buttons, an application programmer can do the following: 

• Display both text and bit maps on the same button. 

• Animate a series of bit maps. 

• Give the user a two-state button. 

• Change bit maps. 

Graphic buttons permit a more intuitive interaction between a user and an application than standard push buttons do. For example, graphic 
buttons can mimic and enhance the look and feel of the physical controls found on stereo equipment. They can emulate the two-state 
behavior of the Pause button found on cassette decks; scan play buttons on CD players and VCRs; and change or animate bit maps when 
control buttons are pressed. 

The graphic button class is registered by calling WinRegisterGraphicButton. 


WinRegisterGraphicButton 


WinRegisterGraphicButton - Syntax 


This function registers the graphic button window class. 


#def ine INCL_SW 
ftinclude <os2.h> 

BOOL rc; 

rc = WinRegisterGraphicButton ( ) ; 


WinRegisterGraphicButton Return Value - rc 


rc (BOOL) - returns 

The following are return codes indicating success or failure: 


TRUE Success. 

FALSE Failure or not recognized. 


WinRegisterGraphicButton - Parameters 


rc (BOOL) - returns 

The following are return codes indicating success or failure: 


TRUE Success. 

FALSE Failure or not recognized. 


WinRegisterGraphicButton - Example Code 


The following code illustrates registering a graphic button window class. 


#def ine INCL_SW 
#include <os2me.h> 

HWND hwndFrame; 

WinRegisterGraphicButton () ; /* Register a graphic button control */ 

/* Create a Secondary Window */ 

hwndFrame = WinLoadSecondaryWindow (HWND_DESKTOP, 

HWND_DESKTOP , 

MyDlgProc, 

NULL, 

ID_DIALOG, 

NULL) ; 


WinRegisterGraphicButton - Topics 


Select an item: 

Syntax 

Parameters 

Returns 

Example Code 
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Control Data 


The GBTNCDATA data structure contains the information used as the graphic button control data. 


Styles 


The base graphic button provides the ability to display bitmaps and text; it defaults to the Up state. Additional styles can be used to increase 
its function. 


Graphic button controls have the following window styles: 


GBS_TWOSTATE A two-state graphic button has two states-Up and Down. If the button 

is in the Up state, the button is drawn with the Z-order above the 
owner. If the button is in the Down state, the button is drawn with the 
Z-order below the owner. Typically, the Up state expresses to the user 
that the button's action is selectable; while the Down state expresses 
that the action is being processed currently. Related messages are 
GBM_SETSTATE, GBM_QUERYSTATE, GBM_SETBITMAPINDEX, 
and GBM_QUERYBITMAPINDEX. 


GBS_AUTOTWOSTATE An automatic two-state graphic button automatically toggles its state 

from Up to Down and from Down to Up whenever the user clicks on it. 
No message from the owner is required for the button to toggle its 
state. Related messages are GBM_SETSTATE, GBM_QUERYSTATE, 
GBM_SETBITMAPINDEX, and GBM_QUERYBITMAPINDEX. 

If both GBS_TWOSTATE and GBS_AUTOTWOSTATE are set, 
GBS_AUTOTWOSTATE takes precedence. 

GBS_ANIMATION An animation graphic button can animate a series of bitmaps. The 

bitmaps are displayed in ascending sequential order. The series is 
treated as a circular list: when the last bitmap of the series is reached, 
the next bitmap displayed is the first in the series. Related messages 
are GBM_ANIMATE, GBM_QUERYANIMATIONACTIVE, 
GBM_SETANIMATIONRATE, GBM_QUERYANIMATIONRATE, 
GBM_SETBITMAPINDEX, and GBM_QUERYBITMAPINDEX. 

GBS_AUTOANIMATION An automatic animation graphic button automatically toggles the 

animation from On to Off and from Off to On whenever the user clicks 
on it. Related messages are GBM_ANIMATE, 
GBM_QUERYANIMATIONACTIVE, GBM_SETANIMATIONRATE, 
GBM_QUERYANIMATIONRATE, GBM_SETBITMAPINDEX, and 
GBM_QUERYBITMAPINDEX. 

If both GBS_ANIMATION and GBS_AUTOANIMATION are set, 
GBS_AUTOANIMATION takes precedence. 


GBS_HILITEBITMAP 


This style permits display of a different bitmap when the graphic button 
is in the highlighted paint state. The highlighted paint state occurs 


GBS_DISABLEBITMAP 


GBS_3D_TEXTRECESSED 


GBS_3D_TEXTRAISED 


when the user presses the pointer button while over the graphic button 
or holds the spacebar down when the graphic button has the focus. 
This bitmap is set by the GBM_SETBITMAPINDEX message with 
GB_HILITE as the specified index to change. Related messages are 
GBM_SETBITMAPINDEX and GBM_QUERYBITMAPINDEX. 

This style permits display of a different bitmap when the graphic button 
is in the disabled paint state. This bitmap is set by the 
GBM_SETBITMAPINDEX message with GB_DISABLE as the 
specified index to change. Related messages are 
GBM_SETBITMAPINDEX and GBM_QUERYBITMAPINDEX. 

The text on the graphic button is displayed three-dimensionally. The 
Z-order of the text is below the face of the graphic button. The text is 
drawn with its main body black, and the bottom and right edges white. 

The text on the graphic button is displayed three-dimensionally. The 
Z-order of the text is above the face of the graphic button. The text is 
drawn with its main body white, and the bottom and right edges black. 

If both GBS_3D_TEXTRECESSED and GBS_3D_TEXTRAISED are 
set, GBS_3D_TEXTRAISED takes precedence. 


Control Messages 


Graphic buttons use the following messages: 


Message 
GBM_AN I MATE 

GBM_QUERYAN IMAT I ONACT I VE 
GBM_QUERYAN IMAT I ONRATE 

GBM_QUERYB I TMAP INDEX 
GBM_QUERY S TATE 
GBM_QUERYTEXTPOSITION 
GBM_SE TAN IMAT I ONRATE 
GBM_SETB I TMAP INDEX 

GBM_SETGRAPHICDATA 


Description 

Sets the animation of an 
animate-able graphic button On 
or Off. 

Returns the animation state of 
the graphic button. 

Returns the animation rate of 
a graphic button in 
milliseconds . 

Returns the bitmap index of 
the queried button parameter. 

Returns the current state of 
the graphic button. 

Returns the text positioning 
relative to the bitmap. 

Sets the animation rate of a 
animate-able graphic button. 

Sets the bitmap index to use 
during various states of the 
graphic button. 

An application sends this 
message to change the 
graphical data of the graphic 
button . 


GBM_SETSTATE Sets the state of a two-state 

graphic button. 

GBM_SETTEXTPOSITION Sets the text positioning 

relative to the bitmap. 


WM COMMAND 


WMCOMMAND Field - usCommand 

usCommand (USHORT) 

The command value. The application must relate the command to an application function. 

WM COMMAND Field - usSource 

usSource (USHORT) 

Identifies the type of control that generated this command as CMDSRC_PUSHBUTTON. 


WMCOMMAND 

Field - usPointer 

usPointer (USHORT) 

The pointer-device indicator. 



WMCOMMAND 

Return Value - rc 

rc (ULONG) 

Reserved. 



WM COMMAND 

- Parameters 


usCommand (USHORT) 

The command value. The application must relate the command to an application function. 


usSource (USHORT) 

Identifies the type of control that generated this command as CMDSRC_PUSHBUTTON. 


usPointer (USHORT) 

The pointer-device indicator. 


rc (ULONG) 

Reserved. 


WMCOMMAND - Description 


This message occurs when the graphic button has a significant event to notify its owner. 


paraml 


USHORT 

usCommand 

/* 

Command value. */ 

param2 

USHORT 

usSource 

/* 

Source of command. */ 

USHORT 

usPointer 

/* 

Pointer-device indicator. */ 


WM COMMAND - Topics 


Select an item: 

Description 

Parameters 

Returns 
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WM CONTROL 


WM CONTROL Field - usID 


usID (USHORT) 

The identity of the graphic button that generated the notification. 


WM CONTROL Field - usnotifycode 


usnotifycode (USHORT) 

The notification codes that indicate what action has occurred. 

GBN_BUTTONUP 

Returned when the button is in the Up position. param2 is reserved. 
GBN_BUTTONDOWN 

Returned when the button is in the Down position. param2 is reserved. 
GBN_BUTTONHILITE 

Returned when the button is selected to the On position. param2 is reserved 

GBN_SETFOCUS 

Returned when the button is gaining or losing focus. param2 is reserved. 


WM CONTROL Field - ulnotifyspec 


ulnotifyspec (ULONG) 

Notify command-specific information. 


WM CONTROL Return Value - ulReserved 


ulReserved (ULONG) 

Reserved. 


WM CONTROL - Parameters 


usID (USHORT) 

The identity of the graphic button that generated the notification. 

usnotifycode (USHORT) 

The notification codes that indicate what action has occurred. 

GBN_BUTTONUP 

Returned when the button is in the Up position. param2 is reserved. 
GBN_BUTTONDOWN 

Returned when the button is in the Down position. param2 is reserved. 
GBN_BUTTONHILITE 

Returned when the button is selected to the On position. param2 is reserved 

GBN_SETFOCUS 

Returned when the button is gaining or losing focus. param2 is reserved. 


ulnotifyspec (ULONG) 

Notify command-specific information. 


ulReserved (ULONG) 


Reserved. 


WMCONTROL - Description 


This message provides notification codes initiated by the graphic button control window to notify its owner of significant events. 


paraml 

USHORT usID /* 

USHORT usnotifycode /* 


Graphic button ID. */ 
Notification code. */ 


param2 

ULONG 


ulnotifyspec /* 


Command-specific info. */ 


WM CONTROL - Remarks 


These notifications are generated by all graphic buttons. The para m2 field is reserved. 


WM CONTROL - Default Processing 


None. 


WM CONTROL - Topics 


Select an item: 
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Returns 

Remarks 
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GBM ANIMATE 


GBM ANIMATE Field - usStart 


usStart (USHORT) 

Start/stop animation 


TRUE 

Start animating the graphic button. 

FALSE 

Stop animating the graphic button. 


GBMANIMATE Field - usContinue 

usContinue (USHORT) 

Starting point of animation. 


TRUE 

Animation starts with the currently shown bitmap. For example, if the graphic button is in the Down state, the 
animation begins with the Down bitmap and continues with subsequent bitmaps in the array until the end of the 
animation series. Then, the animation restarts at the beginning of the animation series (but not necessarily with the 
Down bitmap). 

FALSE 

Animation starts at the beginning of the animation bitmap series. The start of this series can be specified by a 
GBM_SETBITMAPINDEX message. 


GBM ANIMATE Return Value - rc 

rc (ULONG) 

Return codes indicating success or failure. 


TRUE 

Success. 

FALSE 

Failure or not recognized. 


GBM ANIMATE - Parameters 

usStart (USHORT) 

Start/stop animation. 


TRUE 

Start animating the graphic button. 

FALSE 

Stop animating the graphic button. 


usContinue (USHORT) 

Starting point of animation. 


TRUE 


Animation starts with the currently shown bitmap. For example, if the graphic button is in the Down state, the 
animation begins with the Down bitmap and continues with subsequent bitmaps in the array until the end of the 
animation series. Then, the animation restarts at the beginning of the animation series (but not necessarily with the 
Down bitmap). 


FALSE 

Animation starts at the beginning of the animation bitmap series. The start of this series can be specified by a 
GBM_SETBITMAPINDEX message. 

rc (ULONG) 

Return codes indicating success or failure. 

TRUE 

Success. 

FALSE 

Failure or not recognized. 


GBM ANIMATE - Description 


This message sets the animation of an animate-able graphic button to On or Off. 


paraml 

USHORT usStart /* Start/stop animation. */ 

param2 

USHORT usContinue /* Starting point of animation. */ 


GBM ANIMATE - Remarks 


This message does not have any effect if the graphic button is not of style GBS_ANIMATE or GBS_AUTOANIMATE. 


GBM_ANIMATE - Topics 


Select an item: 
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GBM QUERYANIMATIONACTIVE 


GBM QUERYANIMATIONACTIVE Field - ulReserved 


ulReserved (ULONG) 

Reserved. 

GBMQUERYANIMATIONACTIVE Field - ulReserved 

ulReserved (ULONG) 

Reserved. 

GBM QUERYANIMATIONACTIVE Return Value - rc 

rc (ULONG) 

Return codes indicating success or failure. 


TRUE 

FALSE 

Animation is active. The graphic button is currently animating. 


Animation is not active. The graphic button is not currently animating. 


GBM QUERYANIMATIONACTIVE - Parameters 

ulReserved (ULONG) 

Reserved. 

ulReserved (ULONG) 

Reserved. 

rc (ULONG) 

Return codes indicating success or failure. 


TRUE 

FALSE 

Animation is active. The graphic button is currently animating. 


Animation is not active. The graphic button is not currently animating. 


GBM QUERYANIMATIONACTIVE - Description 


This message returns the animation state of the graphic button. 


paraml 

ULONG ulReserved /* Reserved. */ 
param2 

ULONG ulReserved /* Reserved. */ 


GBM QUERYANIMATIONACTIVE - Topics 

Select an item: 
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GBM QUERYANIMATIONRATE 


GBM QUERYANIMATIONRATE Field - ulReserved 


ulReserved (ULONG) 
Reserved. 


GBM QUERYANIMATIONRATE Field - ulReserved 


ulReserved (ULONG) 
Reserved. 


GBM QUERYANIMATIONRATE Return Value - rc 


rc (ULONG) 

The animation rate, in milliseconds, used for this graphic button. 


GBM QUERYANIMATIONRATE - Parameters 


ulReserved (ULONG) 
Reserved. 

ulReserved (ULONG) 
Reserved. 


rc (ULONG) 

The animation rate, in milliseconds, used for this graphic button. 


GBMQUERYANIMATIONRATE - Description 


This message returns the animation rate of the graphic button in milliseconds. 


paraml 

ULONG ulReserved /* Reserved. */ 
param2 

ULONG ulReserved /* Reserved. */ 


GBM QUERYANIMATIONRATE - Topics 

Select an item: 

Description 

Parameters 

Returns 
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GBM QUERYBITMAPINDEX 


GBM QUERYBITMAPINDEX Field - usGBState 


usGBState (USHORT) 
Bitmap state. 


GBJJP 


Query bitmap used when in the Up state. 


GB_DOWN 

Query bitmap used when in the Down state. 

GB_HILITE 

Query bitmap used when in the highlighted state. 

GB_DISABLE 

Query bitmap used when in the disabled state. 


GB_ANIMATIONBEGIN 

Query bitmap at the beginning of an animation series. 
GB_ANIMATIONEND 

Query bitmap at the end of an animation series. 
GB_CURRENTSTATE 

Query the index of the currently shown bitmap. 


GB_ERROR 

Invalid parameter. 


GBMQUERYBITMAPINDEX Field - ulReserved 

ulReserved (ULONG) 

Reserved. 

GBM QUERYBITMAPINDEX Return Value - rc 

rc (USHORT) 

Bitmap index of the queried button parameter. 

GBM QUERYBITMAPINDEX - Parameters 

usGBState (USHORT) 

Bitmap state. 


GBJJP 

Query bitmap used when in the Up state. 

GB_DOWN 

Query bitmap used when in the Down state. 

GB_HILITE 

Query bitmap used when in the highlighted state. 

GB_DISABLE 

Query bitmap used when in the disabled state. 


GB_ANIMATIONBEGIN 


Query bitmap at the beginning of an animation series. 
GB_ANIMATIONEND 

Query bitmap at the end of an animation series. 
GB_CURRENTSTATE 

Query the index of the currently shown bitmap. 

GB_ERROR 

Invalid parameter. 

ulReserved (ULONG) 

Reserved. 

rc (USHORT) 

Bitmap index of the queried button parameter. 


GBMQUERYBITMAPINDEX - Description 


This message returns the bitmap index of the queried button parameter. 


paraml 

USHORT usGBState /* Bitmap state. */ 

param2 

ULONG ulReserved /* Reserved. */ 


GBM QUERYBITMAPINDEX - Remarks 

If usGBState is not valid, then the index of the currently shown bitmap is returned. 


GBM QUERYBITMAPINDEX - Topics 
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GBM QUERYSTATE 


GBM QUERYSTATE Field - ulReserved 


ulReserved (ULONG) 

Reserved. 

GBMQUERYSTATE Field - ulReserved 

ulReserved (ULONG) 

Reserved. 

GBM QUERYSTATE Return Value - rc 

rc (ULONG) 

Return codes indicating the state of the graphic button. 


GBJJP 

The graphic button is in the Up state. 

GB_DOWN 

The graphic button is in the Down state. 

GBJHILITE 

The graphic button is in the highlighted state. 

GB_ERROR 

An error has occurred. 


GBM QUERYSTATE - Parameters 

ulReserved (ULONG) 

Reserved. 

ulReserved (ULONG) 

Reserved. 

rc (ULONG) 

Return codes indicating the state of the graphic button. 


GBJJP 

The graphic button is in the Up state. 

GB_DOWN 

The graphic button is in the Down state. 

GBJHILITE 

The graphic button is in the highlighted state. 


GB_ERROR 

An error has occurred. 


GBMQUERYSTATE - Description 


This message returns the current state of the graphic button. 


paraml 

ULONG ulReserved /* 
param2 

ULONG ulReserved /* 


Reserved. */ 
Reserved. */ 


GBM QUERYSTATE - Remarks 


Graphic buttons that are not of either GBS_TWOSTATE or GBS_AUTOTWOSTATE styles always are considered in the Up state. 

Animation can occur independently from a change in state of the button. The drawing of animation bitmaps takes precedence over the 
current state bitmap. 

A multi-state button or a button that draws bitmaps in its highlighted or disabled states is not intended to be animated, and animated buttons 
are not intended to have visual states. The combination of these two styles might yield undefined results. 


GBM QUERYSTATE - Topics 
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GBM QUERYTEXTPOSITION 


GBM QUERYTEXTPOSITION Field - ulReserved 


ulReserved (ULONG) 
Reserved. 


GBM QUERYTEXTPOSITION Field - ulReserved 


ulReserved (ULONG) 
Reserved. 


GBM QUERYTEXTPOSITION Return Value - rc 


rc (ULONG) 

Return codes indicating the position of the graphic button. 
GB_TEXTBELOW 

The graphic button text is located below the bitmap. 

GB_TEXTABOVE 

The graphic button text is located above the bitmap. 


GBM QUERYTEXTPOSITION - Parameters 


ulReserved (ULONG) 

Reserved. 

ulReserved (ULONG) 

Reserved. 

rc (ULONG) 

Return codes indicating the position of the graphic button. 
GB_TEXTBELOW 

The graphic button text is located below the bitmap. 

GB_TEXTABOVE 

The graphic button text is located above the bitmap. 


GBM QUERYTEXTPOSITION - Description 

This message returns text positioning relative to the bitmap. 


paraml 

ULONG ulReserved /* Reserved. */ 


param2 

ULONG ulReserved /* Reserved. */ 


GBM QUERYTEXTPOSITION - Topics 

Select an item: 

Description 

Parameters 

Returns 
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GBM SETANIMATIONRATE 


GBM SETANIMATIONRATE Field - ulMil 


ulMil (ULONG) 

The rate at which bit maps are displayed from the animation series. The rate is specified as the period between bit-map updates in 
milliseconds. 


GBM SETANIMATIONRATE Field - ulReserved 


ulReserved (ULONG) 
Reserved. 


GBM SETANIMATIONRATE Return Value - rc 


rc (ULONG) 

Return code indicating success or failure. 
TRUE 

Success. 


FALSE 


Failure or not recognized. 


GBM SETANIMATIONRATE - Parameters 


ulMil (ULONG) 

The rate at which bit maps are displayed from the animation series. The rate is specified as the period between bit-map updates 
milliseconds. 

ulReserved (ULONG) 

Reserved. 

rc (ULONG) 

Return code indicating success or failure. 

TRUE 

Success. 

FALSE 

Failure or not recognized. 


GBMSETANIMATIONRATE - Description 

This message sets the animation rate of an animate-able graphic button. 


paraml 


ULONG 

ulMil 

/* 

Rate at which bit maps are displayed 

param2 

ULONG 

ulReserved 

/* 

Reserved. */ 


GBM SETANIMATIONRATE - Remarks 


This message does not have any effect if the graphic button is not of GBS_ANIMATE or GBS_AUTOANIMATE styles. 


GBM SETANIMATIONRATE - Topics 


Select an item: 

Description 

Parameters 
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Remarks 
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GBM SETBITMAPINDEX 


GBM SETBITMAPINDEX Field - usGBState 


usGBState (USHORT) 

State of graphic button whose index is to be changed. 


GBJJP 


GB_DOWN 

GBJHILITE 

GB_DISABLE 


Set the bitmap used when in the Up state. 

Set the bitmap used when in the Down state. 

Set the bitmap used when in the highlighted state. 
Set the bitmap used when in the disabled state. 


GB_ANIMATIONBEGIN 


Where animation must begin. 
GB_ANIMATIONEND 

Where animation must end. 
GB_CURRENTSTATE 


Refers to either up or down bitmaps; depends on whether the button is in the Up or Down state. 


GBM SETBITMAPINDEX Field - usFrameCode 


usFrameCode (USHORT) 

Frame code. 

GB_INDEX_FORWARD 

Advance to next bitmap index in circular array. 
GBINDEXBACKWARD 

Set to previous bitmap index in circular array. 
GB_INDEX_FIRST 

Set to first bitmap index. 

GB_INDEX_LAST 

Set to last bitmap index. 

desired_bit_map 

Otherwise, use usFrameCode number as the bitmap index. 


GBM SETBITMAPINDEX Return Value - rc 


rc (ULONG) 

The return code indicating success or failure. 
TRUE 

Success. 


FALSE 


Failure or not recognized. 


GBM SETBITMAPINDEX- Parameters 


usGBState (USHORT) 

State of graphic button whose index is to be changed. 


GBJJP 


GB_DOWN 

GB_HILITE 

GB_DISABLE 


Set the bitmap used when in the Up state. 

Set the bitmap used when in the Down state. 

Set the bitmap used when in the highlighted state. 
Set the bitmap used when in the disabled state. 


GB_ANIMATIONBEGIN 


Where animation must begin. 
GB_ANIMATIONEND 

Where animation must end. 
GB_CURRENTSTATE 


Refers to either up or down bitmaps; depends on whether the button is in the Up or Down state. 

usFrameCode (USHORT) 

Frame code. 


GB_INDEX_FORWARD 

Advance to next bitmap index in circular array. 
GB_INDEX_BACKWARD 

Set to previous bitmap index in circular array. 
GBINDEXFIRST 

Set to first bitmap index. 

GB_INDEX_LAST 

Set to last bitmap index. 

desired_bit_map 

Otherwise, use usFrameCode number as the bitmap index. 

rc (ULONG) 

The return code indicating success or failure. 


TRUE 

FALSE 


Success. 

Failure or not recognized. 


GBM SETBITMAPINDEX - Description 


This message sets the bitmap index to use during various states of the graphic button. 


paraml 

USHORT usGBState /* State of graphic button whose index is to be changed. */ 
param2 

USHORT usFrameCode /* Frame code. */ 


GBM SETBITMAPINDEX- Remarks 


If starting, the animation bit should be less than or equal to the ending animation bitmap index. 
Setting the bitmap index for unused states is undefined. 


GBM SETBITMAPINDEX - Topics 
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GBM SETGRAPHICDATA 


GBM SETGRAPHICDATA Field - gbtncdata 


gbtncdata (PGBTNCDATA) 

New graphic button data to use. 


GBM SETGRAPHICDATA Field - ulReserved 


ulReserved (ULONG) 
Reserved. 


GBM SETGRAPHICDATA Return Value - rc 


rc (ULONG) 

Return code indicating success or failure. 
TRUE 

Success. 


FALSE 


Failure or not recognized. 


GBM SETGRAPHICDATA- Parameters 


gbtncdata (PGBTNCDATA) 

New graphic button data to use. 

ulReserved (ULONG) 

Reserved. 


rc (ULONG) 

Return code indicating success or failure. 


TRUE 

FALSE 


Success. 

Failure or not recognized. 


GBMSETGRAPHICDATA - Description 

An application sends this message to change the graphical data of the graphic button. This data includes the text and bit maps. 


paraml 


PGBTNCDATA 

gbtncdata 

/* 

New graphic button data to use 

param2 

ULONG 

ulReserved 

/* 

Reserved. */ 


GBM SETGRAPHICDATA- Remarks 


Setting the graphic button data with this message erases all previous data related to the state of the graphic button. The state of the graphic 
button will be set to the default parameters. 

WinSetWindowText can be used to change the text of the graphic button without altering the button's parameters or state. 


GBM SETGRAPHICDATA - Example Code 


The following code illustrates how to change graphical data for a graphic button. 


typedef struct { 

USHORT usReserved; 

PSZ pszText; 

HMODULE hmod; 

USHORT cBitmaps; 

USHORT aidBitmap [ 1 ] ; 

} GBTNCDATA; 

typedef GBTNCDATA *PGBTNCDATA; 


/♦Reserved field ♦/ 

/♦Initial text of button ♦/ 
/♦Module handle for bit maps */ 
/♦Number of bit maps */ 

/♦Array of bit-map IDs ♦/ 


GBTNCDATA cdata; 


cdata . usReserved = GB_STRUCTURE; 

cdata .pszText = "Play"; 

cdata. hmod = hmodBitmaps; 

cdata . cBitmaps = 1; 

cdata . aidBitmap [ 0 ] = ID_PLAY; 

WinSendMsg ( hwndButton, GBM_SETGRAP HI CDATA, (MPARAM) &cdata, OL; 


GBM SETGRAPHICDATA - Topics 
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GBM SETSTATE 


GBM SETSTATE Field - usStateCode 


usStateCode (USHORT) 
State code. 


GBJJP 

GB_DOWN 

GB_TOGGLE 


Sets the graphic button to the Up state. 

Sets the graphic button to the Down state. 

Toggles the graphic buttons state from Up to Down or from Down to Up. 


GBM SETSTATE Field - usRePaint 


usRePaint (USHORT) 

Indicates when change of state will occur. 

TRUE 

The change in state is reflected immediately onscreen. 


FALSE 


The change in state is not reflected immediately onscreen. The graphic button displays the change the next time it 


receives a BN_PAINT message. 


GBMSETSTATE Return Value - rc 

rc (ULONG) 

Return codes indicating success or failure. 


TRUE 

FALSE 

Success. 


Failure or not recognized. 


GBM SETSTATE - Parameters 

usStateCode (USHORT) 

State code. 


GBJJP 

GB_DOWN 

Sets the graphic button to the Up state. 

GB_TOGGLE 

Sets the graphic button to the Down state. 


Toggles the graphic buttons state from Up to Down or from Down to Up. 


usRePaint (USHORT) 

Indicates when change of state will occur. 


TRUE 

FALSE 

The change in state is reflected immediately onscreen. 


The change in state is not reflected immediately onscreen. The graphic button displays the change the next time it 
receives a BN_PAINT message. 


rc (ULONG) 

Return codes indicating success or failure. 


TRUE 

FALSE 

Success. 


Failure or not recognized. 


GBM SETSTATE - Description 

This message sets the state of a two-state graphic button. 

paraml 

USHORT usStateCode /* State code. */ 


param2 


USHORT usRePaint 


/* Indicates when change of state will occur. */ 


GBM SETSTATE - Topics 


Select an item: 

Description 

Parameters 

Returns 
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GBM SETTEXTPOSITION 


GBM SETTEXTPOSITION Field - usTextPos 


usTextPos (USHORT) 

Text position. 

GB_TEXTBELOW 

Position text below the bitmap. 

GB_TEXTABOVE 

Position text above the bitmap. 


GBM SETTEXTPOSITION Field - ulReserved 


ulReserved (ULONG) 

Reserved. 


GBM SETTEXTPOSITION Return Value - rc 


rc (USHORT) 

Return codes indicating success or failure. 
TRUE 

Success. 


FALSE 


Failure or not recognized. 


GBM SETTEXTPOSITION - Parameters 


usTextPos (USHORT) 

Text position. 

GB_TEXTBELOW 

Position text below the bitmap. 

GB_TEXTABOVE 

Position text above the bitmap. 


ulReserved (ULONG) 
Reserved. 


rc (USHORT) 

Return codes indicating success or failure. 


TRUE 

FALSE 


Success. 

Failure or not recognized. 


GBMSETTEXTPOSITION - Description 

This message sets the text positioning relative to the bitmap. 


paraml 


USHORT 

usTextPos 

/* 

Text position 

param2 

ULONG 

ulReserved 

/* 

Reserved. */ 


GBM SETTEXTPOSITION - Remarks 


The default text position is below the bitmap. If this graphic button has a null text string, then this message has no visual effect. 


GBM SETTEXTPOSITION - Topics 


Select an item: 

Description 

Parameters 
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Remarks 
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Secondary Window Functions 


The secondary window manager provides all the capability of a standard dialog window, but it permits the window to be sizable and 
automatically formats the window and manages the scroll bars. 

The functions that manipulate and control the secondary window are designed to convert easily from the standard dialog manager. 
This section describes the secondary window functions and data structures. 

The following table lists the secondary window functions. 


Function 

Description 

WinCreateSecondaryWindow 

Creates a secondary window from a 
dialog template in memory. 

WinDef Secondary WindowP roc 

Provides the default behavior for 
a secondary window. 

WinDef aultSize 

Sizes the window to its default 
size-the optimal size of the 
dialog window. 

WinDestroySecondaryWindow 

Eliminates a secondary window. 

WinDismiss Secondary Window 

Causes modal 

WinProcessSecondaryWindow or 
WinSecondaryWindow calls to 
return . 

WinlnsertDef aultSize 

Adds the default size function to 
the system menu of a secondary 
window . 

WinLoadSecondary Window 

Creates a secondary window from a 
dialog template in a resource. 

WinProcess Secondary Window 

Processes a modal secondary window 
by dispatching messages while the 
modal window is displayed. 

WinQuerySecondaryHWND 

Returns a window handle to various 
windows created as part of a 
secondary window. 

WinSecondaryMessageBox 

Creates a modal window similar to 
WinMessageBox that can be used to 
display error messages and ask 
questions . 

WinSecondary Window 

Loads and processes a modal 
secondary window and returns the 
result value established by 
WinDismissSecondaryWindow . 


WM INITSECONDARYWINDOW 


WM INITSECONDARYWINDOW Field - ulReserved 


ulReserved (ULONG) 

Reserved value. Set to zero. 


WMINITSECONDARYWINDOW Field - pcreate 


pcreate (PVOID) 

This points to the data area that is passed by the WinLoadSecondaryWindow, WinCreateSecondaryWindow, and 
WinSecondaryWindow functions in their pCreateParams parameter. 


WM INITSECONDARYWINDOW Return Value - ulReserved 


ulReserved (ULONG) 

Reserved value. Set to zero. 


WM INITSECONDARYWINDOW - Parameters 


ulReserved (ULONG) 

Reserved value. Set to zero. 

pcreate (PVOID) 

This points to the data area that is passed by the WinLoadSecondaryWindow, WinCreateSecondaryWindow, and 
WinSecondaryWindow functions in their pCreateParams parameter. 

ulReserved (ULONG) 

Reserved value. Set to zero. 


WM INITSECONDARYWINDOW - Description 

This message occurs when a secondary window is being created. 


paraml 


ULONG 

ulReserved 

/* 

Reserved. */ 

param2 

PVOID 

pcreate 

/* 

Application-defined data area 


WM INITSECONDARYWINDOW- Remarks 


This message occurs after the WMJNITDLG message and after the secondary window is set to its initial size. Application sizing 
adjustments should be made with this message, rather than with WMJNITDLG. 


WMINITSECONDARYWINDOW - Related Messages 


WMJNITDLG 


WM INITSECONDARYWINDOW - Topics 
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WinCreateSecondaryWindow 


WinCreateSecondaryWindow - Syntax 


This function creates a secondary window from a dialog template in memory. 


#def ine INCL_SW 
#include <os2.h> 


HWND 

hwndParent; 

/* 

Parent window handle . 

. */ 

HWND 

hwndOwner; 

/* 

Window-handle owner. 

*/ 

PFNWP 

pfnDlgProc; 

/* 

Secondary window procedure. */ 

PDLGTEMPLATE 

pdlgt; 

/* 

Dialog template. */ 


PVOID 

pCreateParams ; 

/* 

Parameters passed to 

secondary window proc 

HWND 

hwnd; 

/* 

Window handle. */ 



hwnd = WinCreateSecondaryWindow (hwndParent, 

hwndOwner, pfnDlgProc, pdlgt, pCreateParams) ; 


WinCreateSecondaryWindow Parameter - hwndParent 


hwndParent (HWND) - input 

The parent window handle of the secondary window to be created. 


WinCreateSecondaryWindow Parameter - hwndOwner 


hwndOwner (HWND) - input 

The owner-window handle of the secondary window to be created. 


WinCreateSecondaryWindow Parameter - pfnDIgProc 


pfnDIgProc (PFNWP) - input 

The secondary window procedure. 


WinCreateSecondaryWindow Parameter - pdlgt 


pdlgt (PDLGTEMPLATE) - input 

The dialog template that defines the layout of the window. 


WinCreateSecondaryWindow Parameter - pCreateParams 


pCreateParams (PVOID) - input 

The parameters passed to the secondary window procedure on the WMJNITDLG message. 


WinCreateSecondaryWindow Return Value - hwnd 


hwnd (HWND) - returns 


Returns the frame window handle a secondary window. 


WinCreateSecondaryWindow - Parameters 


hwndParent (HWND) - input 

The parent window handle of the secondary window to be created. 
hwndOwner (HWND) - input 

The owner-window handle of the secondary window to be created. 

pfnDIgProc (PFNWP) - input 

The secondary window procedure. 

pdlgt (PDLGTEMPLATE) - input 

The dialog template that defines the layout of the window. 

pCreateParams (PVOID) - input 

The parameters passed to the secondary window procedure on the WMJNITDLG message, 
hwnd (HWND) - returns 

Returns the frame window handle a secondary window. 


WinCreateSecondaryWindow - Remarks 


Refer to WinCreateDIg in the IBM OS/2 Presentation Manager Programming Reference. 


WinCreateSecondaryWindow - Related Functions 


WinDismissSecondaryWindow 

WinSecondaryWindow 

WinLoadSecondaryWindow 

WinProcessSecondaryWindow 


WinCreateSecondaryWindow - Example Code 


The following code illustrates how create a secondary window from a dialog template in memory. 

#def ine INCL_SW 
#include <os2me.h> 

PDLGTEMPLATE pdlgt; 

hmod (modulehandle) 

DosGetResource (NULL, RT_DIALOG, ID_DIALOG, (PVOID) pdlgt); 
WinCreateSecondaryWindow ( HWND_DESKTOP, /* Parent window */ 


HwndOwner 

/* 

Owner window 

*/ 

MyDlgProc, 

/* 

Dialog 

procedure 

*/ 

pdlgt. 

/* 

Dialog 

template 

*/ 

NULL) ; 

/* 

Create 

parameters 

*/ 


WinCreateSecondaryWindow - Topics 
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WinDefSecondaryWindowProc 


WinDefSecondaryWindowProc - Syntax 


This function provides the default behavior for a secondary window. 


#def ine INCL_SW 
#include <os2.h> 


HWND 

hwnd; 

/* 

ULONG 

msg; 

/* 

MPARAM 

mpl ; 

/* 

MPARAM 

mp2 ; 

/* 

MRESULT 

rc; 

/* 


Dialog window handle. */ 
Message identity. */ 
Parameter 1. */ 

Parameter 2. */ 

Returns MRESULT . */ 


rc = WinDefSecondaryWindowProc (hwnd, msg, 
mpl , mp2 ) ; 


WinDefSecondaryWindowProc Parameter - hwnd 


hwnd (FIWND) - input 

Dialog window handle. 


WinDefSecondaryWindowProc Parameter - msg 


msg (ULONG) - input 
Message identity. 


WinDefSecondaryWindowProc Parameter - mpl 


mpl (MPARAM) - input 
Parameter 1 . 


WinDefSecondaryWindowProc Parameter - mp2 


mp2 (MPARAM) - input 
Parameter 2. 


WinDefSecondaryWindowProc Return Value - rc 


rc (MRESULT) - returns 

Returns the MRESULT defined by the message passed to this function. 


WinDefSecondaryWindowProc - Parameters 


hwnd (HWND) - input 

Dialog window handle. 

msg (ULONG) - input 
Message identity. 

mpl (MPARAM) - input 
Parameter 1 . 

mp2 (MPARAM) - input 
Parameter 2. 

rc (MRESULT) - returns 

Returns the MRESULT defined by the message passed to this function. 


WinDefSecondaryWindowProc - Remarks 


A secondary window procedure must reference this function for messages that are not handled explicitly. Refer to WinDefDIgProc in the /BM 
OS/2 Presentation Manager Programming Reference . 


WinDefSecondaryWindowProc - Related Functions 


• WinCreateSecondaryWindow 

■ WinDismissSecondaryWindow 

• WinSecondaryWindow 

■ WinLoadSecondaryWindow 

• WinProcessSecondaryWindow 


WinDefSecondaryWindowProc - Example Code 


The following code illustrates how to provide default behavior for a secondary window. 

#def ine INCL_SW 
((include <os2me.h> 

MRESULT MyDlgProc (HWND hwnd, ULONG msg, MPARAM mpl, MPARAM mp2 ) 
{ 

switch (msg) { 


/* Call WinDefSecondaryWindowProc for default processing */ 
return (WinDefSecondaryWindowProc (hwnd, msg, mpl, mp2)); 


WinDefSecondaryWindowProc - Topics 
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WinDefaultSize 


WinDefaultSize - Syntax 


This function sizes the window to its default size-the optimal size of the dialog window. 


#def ine INCL_SW 
#include <os2.h> 

HWND hwnd; /* Secondary window handle. */ 

BOOL rc; /* Return codes. */ 

rc = WinDefaultSize (hwnd) ; 


WinDefaultSize Parameter - hwnd 


hwnd (HWND) - input 

Secondary window handle. 


WinDefaultSize Return Value - rc 


rc (BOOL) - returns 

Return codes indicating success or failure: 


TRUE 

FALSE 


Success. 

Failure or not recognized. 


WinDefaultSize - Parameters 


hwnd (HWND) - input 

Secondary window handle. 


rc (BOOL) - returns 

Return codes indicating success or failure: 


TRUE 

FALSE 


Success. 

Failure or not recognized. 


WinDefaultSize - Remarks 


Sizes the window to its recommended optimal size. 


WinDefaultSize - Related Functions 

• WinlnsertDefaultSize 


WinDefaultSize - Example Code 


The following code illustrates how to size the window to its default size, or the optimum size of the dialog window. 

#def ine INCL_SW 
#include <os2me.h> 


HWND hwndFrame; 

hwndFrame = WinLoadSecondaryWindow 


WinlnsertDefaultSize (hwndFrame, 
WinDefaultSize (hwndFrame) ; 


(HWND_DESKTOP , 

/* 

Parent window */ 

HWND_DESKTOP , 

/* 

Owner window */ 

MyDlgProc, 

/* 

Dialog procedure*/ 

NULL, 

/* 

Module handle */ 

ID_DIALOG, 

/* 

Resource ID */ 

NULL) ; 

/* 

Create parameter*/ 


"~Default size"); /* Insert Menu Item*/ 
/* Set window to its default size*/ 


WinDefaultSize - Topics 
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WinDestroySecondaryWindow 


Win DestroySecondary Window - Syntax 


This function eliminates a secondary window. 


#def ine INCL_SW 
#include <os2.h> 

HWND hwnd; /* Secondary window to be eliminated. */ 

BOOL rc; /* Return codes. */ 

rc = WinDestroySecondaryWindow (hwnd) ; 


WinDestroySecondaryWindow Parameter - hwnd 


hwnd (HWND) - input 

Secondary window frame to be eliminated. 


WinDestroySecondaryWindow Return Value - rc 


rc (BOOL) - returns 

Return codes indicating success or failure: 


TRUE 

FALSE 


Success. 

Failure or not recognized. 


WinDestroySecondaryWindow - Parameters 


hwnd (HWND) - input 

Secondary window frame to be eliminated. 

rc (BOOL) - returns 

Return codes indicating success or failure: 


TRUE 

FALSE 


Success. 

Failure or not recognized. 


WinDestroySecondaryWindow - Related Functions 


WinCreateSecondaryWindow 

WinLoadSecondaryWindow 


WinDestroySecondaryWindow - Example Code 


The following code illustrates how to destroy secondary windows. 

#def ine INCL_SW 
#include <os2me.h> 

MRESULT EXPENTRY MyDlgProc (HWND hwnd, ULONG msg, MPARAM mpl, MPARAM m 
{ 


switch (msg) { 
case WM_CLOSE : 

/* Destroy a secondary window */ 
WinDestroySecondaryWindow (hwndSecondaryFrame) ; 
return (TRUE) ; 
break; 


return (WinDef SecondaryWindowProc (hwnd, msg, mpl, mp2)); 


WinDestroySecondaryWindow - Topics 
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WinDismissSecondaryWindow 


WinDismissSecondaryWindow - Syntax 


This function causes modal WinProcessSecondaryWindow or WinSecondaryWindow calls to return. 

#def ine INCL_SW 
ftinclude <os2.h> 


HWND 

hwndDlg; 

/* 

Secondary dialog window. */ 

ULONG 

ulResult; 

/* 

Result. */ 

BOOL 

rc; 

/* 

Return codes. */ 


rc = WinDismissSecondaryWindow (hwndDlg, ulResult) ; 


WinDismissSecondaryWindow Parameter - hwndDlg 


hwndDlg (HWND) - input 

Secondary dialog window. 


WinDismissSecondaryWindow Parameter - ulResult 


ulResult (ULONG) - input 

Result to be returned by WinSecondaryWindow or WinProcessSecondaryWindow. 


WinDismissSecondaryWindow Return Value - rc 


rc (BOOL) - returns 

Return codes indicating success or failure: 


TRUE 

FALSE 


Success. 

Failure or not recognized. 


WinDismissSecondaryWindow - Parameters 


hwndDlg (FIWND) - input 

Secondary dialog window. 

ulResult (ULONG) - input 

Result to be returned by WinSecondaryWindow or WinProcessSecondaryWindow. 
rc (BOOL) - returns 

Return codes indicating success or failure: 


TRUE 


Success. 


FALSE 


Failure or not recognized. 


WinDismissSecondaryWindow - Remarks 


Refer to WinDismissDIg in the /BM OS/2 Presentation Manager Programming Reference. 


WinDismissSecondaryWindow - Related Functions 


• WinCreateSecondaryWindow 

• WinDefSecondaryWindowProc 

• WinSecondaryWindow 

• WinLoadSecondaryWindow 

• WinProcessSecondaryWindow 


WinDismissSecondaryWindow - Example Code 


The following code illustrates how to cause modal WinProcessSecondaryWindows or WinSecondaryWindow calls to return. 


#def ine INCL_SW 
#include <os2me.h> 

case WM_COMMAND : 

switch (SHORT1FROMMP (mpl) ) { 

case DID_CANCEL : 

/* Dismiss the window */ 

WinDismissSecondaryWindow (hwnd, DID_CANCEL) ; 
break; 

} 


WinDismissSecondaryWindow - Topics 
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WinlnsertDefaultSize 


WinlnsertDefaultSize - Syntax 


This function adds the default size function to the system menu of a secondary window. 


#def ine INCL_SW 
#include <os2.h> 


HWND 

hwnd; 

/* 

Secondary window handle . 

PSZ 

pszDefaultSize; 

/* 

Text for system menu. */ 

BOOL 

rc; 

/* 

Return codes. */ 


rc = WinlnsertDef aultSize (hwnd, pszDef aultSize) ; 


WinlnsertDefaultSize Parameter - hwnd 


hwnd (HWND) - input 

Secondary window handle. 


WinlnsertDefaultSize Parameter - pszDefaultSize 


pszDefaultSize (PSZ) - input 

Text to be inserted into the system menu. Usually, this will read "Default Size”. 


WinlnsertDefaultSize Return Value - rc 


rc (BOOL) - returns 

Return codes indicating success or failure: 


TRUE 

FALSE 


Success. 

Failure or not recognized. 


WinlnsertDefaultSize - Parameters 


hwnd (HWND) - input 

Secondary window handle. 


pszDefaultSize (PSZ) - input 

Text to be inserted into the system menu. Usually, this will read "Default Size”, 
rc (BOOL) - returns 

Return codes indicating success or failure: 


TRUE 

FALSE 


Success. 

Failure or not recognized. 


WinlnsertDefaultSize - Remarks 


The function adds Default Size to the system menu of a secondary window. Because a secondary window is a sizable dialog, its initial size 
is the optimal size for the dialog. After the window is sized, scroll bars appear when necessary. The default size function returns the window 
to its optimal size. 


WinlnsertDefaultSize - Related Functions 


WinDefaultSize 


WinlnsertDefaultSize - Example Code 


The following code illustrates adding the default size function to the system menu of a secondary window. 

#def ine INCL_SW 
#include <os2me.h> 


HWND hwndFrame; 


hwndFrame = WinLoadSecondaryWindow 


(HWND_DESKTOP , 

/* 

Parent window */ 

HWND_DESKTOP , 

/* 

Owner window */ 

MyDlgProc, 

/* 

Dialog procedure*/ 

NULL, 

/* 

Module handle */ 

ID_DIALOG, 

/* 

Resource ID */ 

NULL) ; 

/* 

Create parameter*/ 


WinlnsertDefaultSize (hwndFrame, "~Default size"); /* Insert menu item */ 
WinDefaultSize (hwndFrame) ; /* Set window to its default size */ 


WinlnsertDefaultSize - Topics 


Select an item: 
Syntax 
Parameters 
Returns 


Remarks 
Example Code 
Related Functions 
Glossary 


WinLoadSecondaryWindow 


WinLoadSecondaryWindow - Syntax 


This function creates a secondary window from a dialog template in a resource. The secondary window is modeless. 


#def ine 

INCL_SW 




#include 

<os2 . h> 




HWND 

hwndParent ; 

/* 

Parent window handle . 

*/ 

HWND 

hwndOwner; 

/* 

Owner window handle . 

*/ 

PFNWP 

pfnDlgProc; 

/* 

Secondary window procedure. */ 

HMODULE 

hmod; 

/* 

Module handle. */ 


ULONG 

idDlg; 

/* 

Resource ID of dialog 

template. */ 

PVOID 

pCreateParams ; 

/* 

Parameters passed to 

secondary window proc 

HWND 

hwnd; 

/* 

Window handle. */ 



hwnd = WinLoadSecondaryWindow (hwndParent, 

hwndOwner, pfnDlgProc, hmod, idDlg, 
pCreateParams) ; 


WinLoadSecondaryWindow Parameter - hwndParent 


hwndParent (HWND) - input 

Parent window handle of the created secondary frame window. 


WinLoadSecondaryWindow Parameter - hwndOwner 


hwndOwner (HWND) - input 

Requested owner-window handle of the created secondary frame. 


WinLoadSecondaryWindow Parameter - pfnDlgProc 


pfnDIgProc (PFNWP) - input 

Secondary window procedure for the created dialog window. This is a dialog procedure, except that it calls 
WinDefSecondaryWindowProc. 


WinLoadSecondaryWindow Parameter - hmod 


hmod (HMODULE) - input 

Module handle for resource module. 


WinLoadSecondaryWindow Parameter - idDIg 


idDIg (ULONG) - input 

Resource ID of dialog template in the resources of module hmod. 


WinLoadSecondaryWindow Parameter - pCreateParams 


pCreateParams (PVOID) - input 

Passed to the secondary window procedure in the WMJNITDLG message. 


WinLoadSecondaryWindow Return Value - hwnd 


hwnd (HWND) - returns 

Returns the frame handle of the secondary window. 


WinLoadSecondaryWindow - Parameters 


hwndParent (HWND) - input 

Parent window handle of the created secondary frame window. 
hwndOwner (HWND) - input 

Requested owner-window handle of the created secondary frame. 
pfnDIgProc (PFNWP) - input 

Secondary window procedure for the created dialog window. This is a dialog procedure, except that it calls 
WinDefSecondaryWindowProc. 


hmod (HMODULE) - input 

Module handle for resource module. 

idDIg (ULONG) - input 

Resource ID of dialog template in the resources of module hmod. 

pCreateParams (PVOID) - input 

Passed to the secondary window procedure in the WMJNITDLG message, 
hwnd (HWND) - returns 

Returns the frame handle of the secondary window. 


WinLoadSecondaryWindow - Remarks 


This call creates a standard frame window with a dialog window as the child of the FID_CLIENT window. Refer to WinLoadDIg in the /BM 
OS/2 Presentation Manager Programming Reference. 


WinLoadSecondaryWindow - Related Functions 


• WinCreateSecondaryWindow 

• WinDefSecondaryWindowProc 

■ WinDestroySecondaryWindow 

• WinDismissSecondaryWindow 

■ WinSecondaryWindow 

• WinProcessSecondaryWindow 


WinLoadSecondaryWindow - Example Code 


The following code illustrates creating a secondary window from a dialog template in a resource. 

#def ine INCL_SW 
#include <os2me.h> 


HWND hwndFrame; 


hwndFrame = WinLoadSecondaryWindow 

(HWND_DESKTOP , 

/* 

Parent window 

*/ 


HWND_DESKTOP , 

/* 

Owner window 

*/ 


MyDlgProc, 

/* 

Dialog proc 

*/ 


NULL, 

/* 

Module handle 

*/ 


ID_DIALOG, 

/* 

Resource ID 

*/ 

WinShowWindow (hwndFrame, TRUE) ; 

NULL) ; 

/* 

Create params 

*/ 


WinLoadSecondaryWindow - Topics 
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WinProcessSecondaryWindow 


WinProcessSecondaryWindow - Syntax 


This function processes a modal secondary window by dispatching messages while the modal window is displayed. 


#def ine INCL_SW 
#include <os2.h> 

HWND hwndSW; /* Secondary window handle. */ 

ULONG rc; /* Result. */ 

rc = WinProcessSecondaryWindow (hwndSW) ; 


WinProcessSecondaryWindow Parameter - hwndSW 


hwndSW (HWND) - input 

Secondary frame window handle to process. 


WinProcessSecondaryWindow Return Value - rc 


rc (ULONG) - returns 

Returns the result passed to WinDismissSecondaryWindow. 


WinProcessSecondaryWindow - Parameters 


hwndSW (HWND) - input 

Secondary frame window handle to process. 


rc (ULONG) - returns 

Returns the result passed to WinDismissSecondaryWindow. 


WinProcessSecondaryWindow - Remarks 


Refer to WinProcessDIg in the /BM OS/2 Presentation Manager Programming Reference . 


WinProcessSecondaryWindow - Related Functions 


• WinCreateSecondaryWindow 

• WinDefSecondaryWindowProc 

■ WinDestroySecondaryWindow 

• WinDismissSecondaryWindow 

■ WinSecondaryWindow 


WinProcessSecondaryWindow - Example Code 


The following code illustrates processing a modal secondary window by dispatching messages while the modal window is displayed. 

#def ine INCL_SW 
#include <os2me.h> 

HWND hwndFrame; 

hwndFrame = WinLoadSecondaryWindow (HWND_DESKTOP, 

HWND_DESKTOP , 

MyDlgProc, 

NULL, 

ID_DIALOG, 

NULL) ; 

WinProcessSecondaryWindow (hwndFrame) ; 


/* Parent window */ 
/* Owner window */ 
/* Dialog proc */ 
/* Module handle */ 
/* Resource ID */ 
/* Create params */ 


WinProcessSecondaryWindow - Topics 
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WinQuerySecondaryHWND 


WinQuerySecondaryHWND - Syntax 


This function returns a window handle to various windows created as a part of a secondary window. 

#def ine INCL_SECONDARYWINDOW 
#include <os2.h> 


HWND 

hwnd; 

/* 

Secondary window handle 

ULONG 

ulFlag; 

/* 

Flags. */ 

HWND 

hwnd; 

/* 

Reqested window handle. 


hwnd = WinQuerySecondaryHWND (hwnd, ulFlag) ; 


WinQuerySecondaryHWND Parameter - hwnd 


hwnd (HWND) - input 

Secondary window handle. 


WinQuerySecondaryHWND Parameter - ulFlag 


ulFlag (ULONG) - input 
Flags. 

QS_FRAME 

Returns the HWND for the outer standard frame window. 

QS_DIALOG 

Returns the HWND for the inner dialog frame window. 


WinQuerySecondaryHWND Return Value - hwnd 


hwnd (HWND) - returns 

Returns the requested window handle. 


WinQuerySecondaryHWND - Parameters 


hwnd (HWND) - input 

Secondary window handle. 

ulFlag (ULONG) - input 
Flags. 

QS_FRAME 

Returns the FIWND for the outer standard frame window. 

QS_DIALOG 

Returns the FIWND for the inner dialog frame window. 


hwnd (HWND) - returns 

Returns the requested window handle. 


WinQuerySecondaryHWND - Remarks 


This function returns the handle to the outer frame window or the inner dialog frame window of a secondary window, depending on the 
handle supplied as input. 

Secondary windows utilize two frame windows: a standard frame and a dialog window to implement the sizing and scrolling features. The 
window handle returned from WinLoadSecondaryWindow is the handle to the standard frame. The window handle passed to the message 
procedure specified in WinLoadSecondaryWindow is the dialog window handle. 

The standard frame window handle must be used when associating a help instance and to do WinSetWindowPos operations. 

The dialog window handle should be used as the owner for message boxes and to access the controls on the dialog with 
WinWindowFromID. 

To modify the title bar or the system menu, the application must specify the standard frame window and not the dialog window. 


WinQuerySecondaryHWND - Related Functions 


• WinCreateSecondaryWindow 

■ WinDefSecondaryWindowProc 

• WinDestroySecondaryWindow 

■ WinDismissSecondaryWindow 

• WinLoadSecondaryWindow 

• WinSecondaryWindow 


WinQuerySecondaryHWND - Example Code 

The following code illustrates returning a window handle to various windows created as a part of a secondary window. 

#def ine INCL_SECONDARYWINDOW 
#include <sw.h> 


HWND hwndFrame, hwndDialog; 


hwndFrame = WinLoadSecondaryWindow (HWND_DESKTOP, /* Parent window */ 


HWND_DESKTOP , 

/* 

Owner window 

*/ 

MyDlgProc, 

/* 

Dialog proc 

*/ 

NULL, 

/* 

Module handle 

*/ 

ID_DIALOG, 

/* 

Resource ID 

*/ 

NULL) ; 

/* 

Create params 

*/ 


hwndDialog = WinQuerySecondaryHWND ( hwnd, QS_DIALOG ) ; 


WinQuerySecondaryHWND - Topics 
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WinSecondaryMessageBox 


WinSecondaryMessageBox - Syntax 


This function creates a modal window, similar to WinMessageBox, that can be used to display error messages and ask questions. 


#def ine INCL_SW 
#include <os2.h> 


HWND 

hwndParent ; 

/* 

Parent window handle. */ 

HWND 

hwndOwner; 

/* 

Owner window handle. */ 

PSZ 

pszText; 

/* 

Message text. */ 

PSZ 

pszCaption; 

/* 

Title of secondary message box window 

ULONG 

idWindow; 

/* 

ID of window. */ 

PSMBINFO 

psmbinfo; 

/* 

Information block. */ 

ULONG 

rc; 

/* 

Results. */ 


rc = WinSecondaryMessageBox (hwndParent, hwndOwner, 
pszText, pszCaption, idWindow, psmbinfo) ; 


WinSecondaryMessageBox Parameter - hwndParent 


hwndParent (HWND) - input 


The parent window handle of the secondary window to be created. 


WinSecondaryMessageBox Parameter - hwndOwner 


hwndOwner (HWND) - input 

The owner-window handle of the secondary window to be created. 


WinSecondaryMessageBox Parameter - pszText 


pszText (PSZ) - input 

The text of the message to be displayed. 


WinSecondaryMessageBox Parameter - pszCaption 


pszCaption (PSZ) - input 

The title of the secondary message box window. 


WinSecondaryMessageBox Parameter - idWindow 


idWindow (ULONG) - input 

The identifier of the secondary message box window. 


WinSecondaryMessageBox Parameter - psmbinfo 


psmbinfo (PSMBINFO) - input 

This is an information block that defines which buttons must be included in the window. 


WinSecondaryMessageBox Return Value - rc 


rc (ULONG) - returns 

Returns the result passed to WinDismissSecondaryWindow; this is the ID of the button that was clicked. 


WinSecondaryMessageBox - Parameters 


hwndParent (HWND) - input 

The parent window handle of the secondary window to be created. 
hwndOwner (HWND) - input 

The owner-window handle of the secondary window to be created. 

pszText (PSZ) - input 

The text of the message to be displayed. 

pszCaption (PSZ) - input 

The title of the secondary message box window. 

idWindow (ULONG) - input 

The identifier of the secondary message box window. 

psmbinfo (PSMBINFO) - input 

This is an information block that defines which buttons must be included in the window, 
rc (ULONG) - returns 

Returns the result passed to WinDismissSecondaryWindow; this is the ID of the button that was clicked. 


WinSecondaryMessageBox - Remarks 


Refer to WinMessageBox in the /BM OS/2 Presentation Manager Programming Reference. 


WinSecondaryMessageBox - Related Functions 


• WinCreateSecondaryWindow 

■ WinDefSecondaryWindowProc 

• WinDestroySecondaryWindow 

■ WinDismissSecondaryWindow 

• WinLoadSecondaryWindow 

• WinSecondaryWindow 


WinSecondaryMessageBox - Example Code 


The following code illustrates creating a modal window, similar to WinMessageBox, that can be used to display error messages and ask 
questions. 

#def ine INCL_SW 
ftinclude <os2me.h> 


SMBD Smbd [ 4 ] 


= {{ 


-Save" , 
{ 
{ 
{ 


ID_SAVE, BS_DEFAULT } , 

-Discard" , ID_DISCARD, 0 } , 

Cancel" , ID_CANCEL, 0}, 

Help" , ID_HELP , BS_HELP } } ; 


SMBINFO Smblnfo; 
ULONG Result; 


Smblnfo . hlcon = NULL; 
Smblnfo . cButtons = 4; 
Smblnfo . hwndNotify = NULL; 
Smblnfo. flStyle = MB_QUERY; 
Smblnfo .psmbd = Smbd; 


Result = WinSecondaryMessageBox (HWND_DESKTOP, 

HWND_DESKTOP , 

"Changes have not been saved.", 
"Title", 

I D_SAVE PROMPT, 

&SmbInfo) ; 


WinSecondaryMessageBox - Topics 
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WinSecondaryWindow 


WinSecondaryWindow - Syntax 


This function loads and processes a modal secondary window and returns the result value established by WinDismissSecondaryWindow. 


#def ine INCL_SW 
#include <os2.h> 


HWND 

hwndParent ; 

/* 

Parent window handle. 

*/ 

HWND 

hwndOwner; 

/* 

Owner window handle. 

*/ 

PFNWP 

pfnDlgProc; 

/* 

Secondary window procedure. */ 

HMODULE 

hmod; 

/* 

Module handle. */ 


ULONG 

idDlg; 

/* 

Resource ID of dialog 

template. */ 

PVOID 

pCreateParams ; 

/* 

Parameters passed to 

secondary window proc 

ULONG 

rc; 

/* 

Results. */ 



rc = WinSecondaryWindow (hwndParent, hwndOwner, 
pfnDlgProc, hmod, idDlg, pCreateParams) ; 


WinSecondaryWindow Parameter - hwndParent 


hwndParent (HWND) - input 

The parent window handle of the WinCreateSecondaryWindow frame. 


WinSecondaryWindow Parameter - hwndOwner 


hwndOwner (HWND) - input 

The owner-window handle of the WinCreateSecondaryWindow frame. 


WinSecondaryWindow Parameter - pfnDIgProc 


pfnDIgProc (PFNWP) - input 

The secondary window procedure for CreateDialogWindow. This is a dialog procedure, except that it calls 
WinDefSecondaryWindowProc. 


WinSecondaryWindow Parameter - hmod 


hmod (HMODULE) - input 

Module handle for resource module. 


WinSecondaryWindow Parameter - idDIg 


idDIg (ULONG) - input 

Resource ID of dialog template in the resources of module hmod. 


WinSecondaryWindow Parameter - pCreateParams 


pCreateParams (PVOID) - input 

This is passed to the secondary window procedure in the WMJNITDLG message. 


WinSecondaryWindow Return Value - rc 


rc (ULONG) - returns 

Return the result passed to WinDismissSecondaryWindow. 


WinSecondaryWindow - Parameters 


hwndParent (HWND) - input 

The parent window handle of the WinCreateSecondaryWindow frame. 
hwndOwner (HWND) - input 

The owner-window handle of the WinCreateSecondaryWindow frame. 
pfnDIgProc (PFNWP) - input 

The secondary window procedure for CreateDialogWindow. This is a dialog procedure, except that it calls 
WinDefSecondaryWindowProc. 

hmod (HMODULE) - input 

Module handle for resource module. 

idDIg (ULONG) - input 

Resource ID of dialog template in the resources of module hmod. 

pCreateParams (PVOID) - input 

This is passed to the secondary window procedure in the WMJNITDLG message, 
rc (ULONG) - returns 

Return the result passed to WinDismissSecondaryWindow. 


WinSecondaryWindow - Remarks 


This call creates a standard frame window with a dialog window as the child of FID_CLIENT. Refer to WinDIgBox in the /BM OS/2 
Presentation Manager Programming Be fere nee. 


WinSecondaryWindow - Related Functions 


■ WinCreateSecondaryWindow 

• WinDefSecondaryWindowProc 

■ WinDestroySecondaryWindow 

• WinDismissSecondaryWindow 

■ WinLoadSecondaryWindow 


WinSecondaryWindow - Example Code 


The following code illustrates how to load and process a modal secondary window and returns the result value established by 
WinDismissSecondaryWindow. 

#def ine INCL_SW 
#include <os2me.h> 

ULONG Result; 

Result = WinSecondaryWindow (HWND_DESKTOP, 

HWND_DESKTOP, 

MyDlgProc, 

NULL, 

ID_DIALOG, 

NULL) ; 


WinSecondaryWindow - Topics 


Select an item: 
Syntax 
Parameters 
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Related Functions 
Glossary 


Secondary Window Data Structures 


This section describes the secondary window data structures. The following table describes the secondary window data structures. 


Data Type 
SMBD 


SMB INFO 


Description 

Defines the button style, text, and ID 
for each button to be included in a 
secondary message box. 

Defines the icon, number of buttons, and 
window style of the secondary message 
box window. 


MMIO Functions 


The multimedia input/output (MMIO) file services are an extension of the base OS/2 file services. Designed to be simple, fast, and flexible, 
the MMIO services-functions, messages, and data structures-enable an application to access and manipulate multimedia data files. These 
files contain a variety of media elements (images, graphics, digital audio, and video) that are in different file formats; for example, RIFF, 


AVC, and M-Motion. 


MMIO services provide a consistent programming interface so that an application can refer to these files, read and write data to the files, 
and query the contents of the files, without having to know anything about the specific format of the files. MMIO services strengthen a 
program's portability, as well as data compatibility, by insulating the application from the underlying file formats. 

Note: As a general comment, all fields in MMIO services data structures that are not used in a given function must be initialized to NULL. 
Flags that are not used, and bits not used within flags, must be set to 0. 

The following table describes the MMIO functions. 


Function 

Description 

mmioAdvance 

Fills and empties the contents of an I/O 
buffer of a file set up for direct I/O 
buffer access. 

mmioAscend 

Ascends out of a chunk in a RIFF file 
that was descended into by mmioDescend 
or created by mmioCreateChunk. 

mmioCFAddElement 

Adds an element to the CGRP chunk of an 
open RIFF compound file. 

mmioCFAddEntry 

Adds an entry to the CTOC chunk of an 
open RIFF compound file. 

mmioCFChangeEntry 

Changes a CTOC entry in an open RIFF 
compound file. 

mmioCFClose 

Closes a RIFF compound file that was 
opened by mmioCFOpen. 

mmioCFCompact 

Compacts the elements of a RIFF compound 
file . 

mmioCFCopy 

Copies the CTOC and CGRP chunks from an 
open RIFF compound file to another RIFF 
compound file. 

mmioCFDeleteEntry 

Deletes a CTOC entry in an open RIFF 
compound file. 

mmioCFFindEntry 

Finds a CTOC entry in an open RIFF 
compound file. 

mmioCFGetlnf o 

Retrieves the CTOC header of an open 
RIFF compound file. 

mmioCFOpen 

Opens a RIFF compound file by name. 

mmioCFSetlnf o 

Modifies information that is stored in 
the CTOC header of an open RIFF compound 
file . 

mmioClose 

Closes a file opened by mmioOpen. 

mmioCreateChunk 

Creates a chunk in a RIFF file that was 
opened by mmioOpen. 

mmioDescend 

Descends into a RIFF file chunk 
beginning at the current file position, 
or searches for a specified chunk. 


mmioDetermineSSIOProc Determines the storage system of the 



media data object. 

mmioFindElement 

Enumerates the entries of a compound 
file . 

mmioFlush 

Forces the contents of an I/O buffer to 
be written to disk. 

mmioFOURCC 

Converts four characters to a 
four-character code (FOURCC) . 


mmioGet Format Name 

Provides the descriptive name of the 
format supported by the IOProc. 

mmioGet Formats 

Provides a list of all format I/O 
procedures available for use. 

mmioGet Header 

Obtains media-specific information about 
data in a file such as the media type, 
media structure, and the size of the 
media structure. 

mmioGet Inf o 

Retrieves information from the file I/O 
buffer to a file opened for buffered 
I/O. 

mmioGet Last Err or 

Returns the last error condition stored 
in ulErrorRet that might contain 
additional information for the analysis 
of the last error routine. 

mmioldentif yFile 

Determines (if possible) the format of a 
file by either using the file name or 
querying currently installed I/O 
procedures to see which IOProc can 
understand and process the specified 
file . 

mmioldentif yStorage System 

Identifies the storage system that 
contains the media data object. 

mmioIniFileCODEC 

Modifies the initialization file 
(MMPMMMIO.INI) for MMIO services. It 
adds, replaces, removes, or finds a 
CODEC procedure in the MMPMMMIO.INI 
file . 

mmioIniFileHandler 

Adds, replaces, removes, or finds an I/O 
procedure in the initialization file 
(MMPMMMIO . INI) . 

mmio I ns tall I OP roc 

Installs an I/O procedure in the MMIO 
IOProc table, removes an IOProc from the 
table, or finds a procedure when given 
its FOURCC identifier. 

mmioLoadCODECProc 

Loads the CODEC Proc and returns the 
entry point. 

mmioOpen 

Opens a file and returns an MMIO handle. 

mmioQueryCODECName 

Returns the CODEC Proc name. 

mmioQueryCODECNameLength 

Returns the length of the CODEC Proc 
name . 

mmioQueryFormat Count 

Provides the number of IOProcs that 
match the requested format. 

mmioQueryHeader Length 

Determines the size of the header for a 
specified file. 

mmioQuerylOProcModuleHandle 

Provides the module handle of an 
IOProc 's DLL. This handle must be used 
to retrieve resources from the DLL. This 
function provides the handle of the DLL 
only if it was loaded by MMIO from the 
MMPMMMIO.INI file. 

mmioRead 

Reads a specified number of bytes from a 
file opened by mmioOpen. 

mmioRemoveElement 

Removes the specified element in a 
compound file. 

mmioSeek 

Changes the current position for 
reading, writing, or both, in a file 
opened by mmioOpen. 

mmioSendMessage 

Sends a message to the I/O procedure 


associated with a file that was opened 
with mmioOpen. 

mmioSet Sets or queries extended file 

information . 


mmioSet Buffer 


mmioSet Header 


Enables or disables buffered I/O, or 
changes the buffer or buffer size, for a 
file that was opened using mmioOpen. 

Sets media-specific information for data 
to be written to a file. 


mmioSet Inf o 


Changes information on a file I/O buffer 
of a file opened for buffered I/O. 


mmioStringToFOURCC 


Converts a null-terminated string to a 
four-character code (FOURCC) . 


mmioWrite 


Writes to a file that was opened using 
mmioOpen . 


mmioAdvance 


mmioAdvance - Syntax 


This function fills and empties the contents of an I/O buffer of a file set up for direct I/O buffer manipulation by mmioGetlnfo. 


#def ine INCL_MMIOOS2 
ftinclude <os2.h> 


HMMIO 

hmmio; 

/* 

Open file handle. */ 

PMMIOINFO 

pmmioinfo; 

/* 

Pointer to MMIOINFO. */ 

USHORT 

usFlags; 

/* 

Flags. */ 

USHORT 

rc; 

/* 

Return codes. */ 


rc = mmioAdvance (hmmio, pmmioinfo, usFlags) ; 


mmioAdvance Parameter - hmmio 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


mmioAdvance Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) - input 

A pointer to the MMIOINFO data structure that was filled in by mmioGetlnfo. 


mmioAdvance Parameter - usFlags 


usFlags (USFIORT) - input 

Specifies options for the operation. Contains one or more of the following flags: 

MMIO_READ 

The buffer is refilled from the file. MMIO_READ is used when the caller has finished reading data from the I/O 
buffer and wants the buffer to be refilled (if possible). 

MMIO_WRITE 

The buffer is written to the file and not refilled from the file. MMIO_WRITE is used when the caller has written to the 
end of the buffer and needs the buffer to be emptied (or expanded, in the case of a memory file). 


mmioAdvance Return Value - rc 


rc (USFIORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRJJNBUFFERED 

The specified file is not opened for buffered I/O. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERR_READ_ONLY_FILE 

A write-advance operation was requested for a read-only file. 

MMIOERR_WRITE_ONLY_FILE 

A read-advance operation was requested for a file opened as write only. 

MMIOERR_WRITE_FAILED 

A write-advance operation failed. 

MMIOERR_READ_FAILED 

A read-advance operation failed. 

MMIOERR_SEEK_FAILED 

A seek operation prior to a write- or read-advance operation failed. 
MMIOERR_NO_FLUSH_NEEDED 

A write-advance operation was requested for the buffer, but the operation was not required. 

MMIOERR_OUTOFMEMORY 

An advance operation requires a buffer. 

MMIOERR_CANNOTEXPAND 

Unable to expand a MEM file for an advance request. 


MMIOERR_FREE_FAILED 

Unable to free a buffer after expanding a MEM file. 


mmioAdvance - Parameters 


hmmio (FIMMIO) - input 

The open file handle returned by mmioOpen. 

pmmioinfo (PMMIOINFO) - input 

A pointer to the MMIOINFO data structure that was filled in by mmioGetlnfo. 
usFlags (USFIORT) - input 

Specifies options for the operation. Contains one or more of the following flags: 

MMIO_READ 

The buffer is refilled from the file. MMIO_READ is used when the caller has finished reading data from the I/O 
buffer and wants the buffer to be refilled (if possible). 

MMIO_WRITE 

The buffer is written to the file and not refilled from the file. MMIO_WRITE is used when the caller has written to the 
end of the buffer and needs the buffer to be emptied (or expanded, in the case of a memory file). 

rc (USFIORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRJJNBUFFERED 

The specified file is not opened for buffered I/O. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERR_READ_ONLY_FILE 

A write-advance operation was requested for a read-only file. 

MMIOERR_WRITE_ONLY_FILE 

A read-advance operation was requested for a file opened as write only. 

MMIOERR_WRITE_FAILED 

A write-advance operation failed. 

MMIOERR_READ_FAILED 

A read-advance operation failed. 

MMIOERR_SEEK_FAILED 

A seek operation prior to a write- or read-advance operation failed. 

MMIOERR_NO_FLUSH_NEEDED 

A write-advance operation was requested for the buffer, but the operation was not required. 

MMIOERRJDUTOFMEMORY 

An advance operation requires a buffer. 

MMIOERR_CANNOTEXPAND 

Unable to expand a MEM file for an advance request. 

MMIOERR_FREE_FAILED 

Unable to free a buffer after expanding a MEM file. 


mmioAdvance - Remarks 


The mmioAdvance function does not change the current file position of the file represented by the hmm/o parameter, that is, pchNext of the 
MMIOINFO structure passed in the pmmioinfo parameter will correspond to the same data position before and after mmioAdvance is called, 
hence pointing to the same piece of data that is now located at the beginning of the buffer. mmioAdvance simply makes available as much 
buffer space as possible for doing direct buffer reading or writing. 

When mmioAdvance returns from a call where the MMIO_READ flag was specified, there will be at least n bytes of data available to be 
read in the I/O buffer (that is, n bytes between pchNext and pchEndReac f), where n is the lesser of the I/O buffer size and the number of 
remaining bytes of data. 

When mmioAdvance returns from a call where the MMIO_WRITE flag was specified, at least n bytes of free space in the I/O buffer (that is, 
n bytes between pchNext and pchEndWrite ) where n is specified in the aut/ntofOJ field of the MMIOINFO structure passed on an 
mmioOpen called if the file is a memory file, or the size of the I/O buffer if the file is not a memory file. 

If the file is opened for reading, the I/O buffer is filled from the disk. If the file is opened for writing and the MMIO_DIRTY flag is set in the 
u/F/ags field of the MMIOINFO structure, the buffer is written to disk. The pchNext , pchEndRead , and pchEndWrite fields of the 
MMIOINFO structure are updated to reflect the new state of the I/O buffer. 

If the file was opened for both reading and writing, and the I/O buffer was written to, the contents of the I/O buffer are written to disk before 
the next buffer is read. 

If you have written to the I/O buffer, you must set the MMIO_DIRTY flag of the u/F/ags field of the MMIOINFO structure before calling 
mmioAdvance. Otherwise, the buffer will not be written to disk. 

The pchNext field must also be updated to reflect the data written in the I/O buffer. The I/O buffer will be written up to (but not including) the 
position indicated by the pchNext field of MMIOINFO. 


mmioAdvance - Related Functions 


mmioGetlnfo 

mmioSetlnfo 


mmioAdvance - Example Code 


The following code illustrates how to advance the I/O buffer. 

HMMIO hmmiol; 

MMIOINFO mmioinfo; 

USHORT usFlags; 

USHORT rc; 


rc = mmioAdvance (hmmiol , &mmioinfo, usFlags) ; 
if (rc) 

/* error */ 
else 


mmioAdvance - Topics 
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mmioAscend 


mmioAscend - Syntax 


This function ascends out of a chunk in a RIFF file that was descended into by mmioDescend or created by mmioCreateChunk. 


#def ine INCL_MMIOOS2 
ftinclude <os2.h> 


HMMIO 

hmmio; 

/* 

Open file handle. */ 

PMMCKINFO 

pckinfo; 

/* 

Pointer to MMCKINFO. */ 

USHORT 

usFlags; 

/* 

Reserved. */ 

USHORT 

rc; 

/* 

Return codes. */ 


rc = mmioAscend (hmmio, pckinfo, usFlags) ; 


mmioAscend Parameter - hmmio 


hmmio (FIMMIO) - input 

The open file handle returned by mmioOpen. 


mmioAscend Parameter - pckinfo 


pckinfo (PMMCKINFO) - input 

A pointer to the MMCKINFO structure that was filled by mmioDescend or mmioCreateChunk. 


mmioAscend Parameter - usFlags 


usFlags (USHORT) - input 

Reserved for future use and must be set to zero. 


mmioAscend Return Value - rc 


rc (USHORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

The parameter passed was not correct. 

MMIOERR_CANNOTWRITE 

The I/O buffer needs to be written to disk but disk space is lacking. 


mmioAscend - Parameters 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 

pckinfo (PMMCKINFO) - input 

A pointer to the MMCKINFO structure that was filled by mmioDescend or mmioCreateChunk. 

usFlags (USHORT) - input 

Reserved for future use and must be set to zero. 

rc (USHORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

The parameter passed was not correct. 

MMIOERR_CANNOTWRITE 

The I/O buffer needs to be written to disk but disk space is lacking. 


mmioAscend - Remarks 


If the chunk was descended into using mmioDescend, then mmioAscend seeks to the location following the end of the chunk (past the extra 


pad byte, if any). If the chunk was created and descended into using mmioCreateChunk or if the MMIO_DIRTY flag in the u/F/ags field (of 
the MMCKINFO structure passed in the pck/nfo parameter) is set, then the current file position is assumed to mark the end of the data 
portion of the chunk. If the chunk size is not the same as the value that was stored in the ckS/ze field of MMCKINFO before 
mmioCreateChunk or mmioDescend was called, then mmioAscend seeks back and corrects the chunk size in the chunk header before 
ascending from the chunk. Also, if the chunk size is odd, then mmioAscend writes a NULL pad byte at the end of the chunk. 


mmioAscend - Related Functions 


mmioCreateChunk 

mmioDescend 

mmioFOURCC 

mmioStringToFOURCC 


mmioAscend - Example Code 


The following code illustrates how to move the file position. 

HMMIO hmmiol; 

MMCKINFO mmckinf o; 

USHORT usFlags; 

USHORT rc; 


memset ( &mmckinfo, ' \0', sizeof (MMCKINFO) ); 
rc = mmioAscend (hmmiol , &mmckinfo, usFlags) ; 
if (rc) 

/* error */ 
else 
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mmioCFAddElement 


mmioCFAddElement - Syntax 


This function adds an element to the compound-file resource-group (CGRP) chunk of an open RIFF compound file. 


#def ine INCL_MMIOOS2 
ftinclude <os2.h> 


HMMCF 

hmmc f ; 

/* 

RIFF file handle. */ 

PSZ 

pszElementName; 

/* 

Pointer to the name of the element 

FOURCC 

fccType; 

/* 

Four-character code. */ 

PCHAR 

pchBuffer; 

/* 

Buffer pointer. */ 

LONG 

cchBytes; 

/* 

Length of buffer. */ 

ULONG 

ulFlags; 

/* 

Flags. */ 

ULONG 

rc; 

/* 

Return codes. */ 


rc = mmioCFAddElement (hmmcf , pszElementName, 

fccType, pchBuffer, cchBytes, ulFlags) ; 


mmioCFAddElement Parameter - hmmcf 


hmmcf (HMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. 


mmioCFAddElement Parameter - pszElementName 


pszElementName (PSZ) - input 

A pointer to the name of the element that is to be added to the compound file resource group (CGRP). The symbols + and | are not 
valid with an element name. Element names follow the same naming conventions as those for the DOS operating system. 


mmioCFAddElement Parameter - fccType 


fccType (FOURCC) - input 

The four-character code (FOURCC) of the element. 


mmioCFAddElement Parameter - pchBuffer 


pchBuffer (PCHAR) - input 

A pointer to the caller-supplied buffer containing the element data. 


mmioCFAddElement Parameter - cchBytes 


cchBytes (LONG) - input 

Length of caller-supplied buffer. 


mmioCFAddElement Parameter - ulFlags 


ulFlags (ULONG) - input 

Specifies options for the operation. Contains 0 or the following flag: 


MMIO_CF_ENTRY_EXISTS 

Set only if the compound-file table of contents (CTOC) entry for this element already exists. 


mmioCFAddElement Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

For this function a null pszE/ement/Vame , pchBuffer , or cchBytes is invalid. 

MMIOERR_READ_ONLY_FILE 

The RIFF compound file is opened as read-only. 

MMIO_CF_FAILURE 

The function failed. A call to mmioGetLastError may return: 

MMIOERRINTERNALSYSTEM 

The operation failed due to an internal system error. 


mmioCFAddElement - Parameters 


hmmcf (FIMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. 


pszElementName (PSZ) - input 

A pointer to the name of the element that is to be added to the compound file resource group (CGRP). The symbols + and | are not 
valid with an element name. Element names follow the same naming conventions as those for the DOS operating system. 


fccType (FOURCC) - input 

The four-character code (FOURCC) of the element. 


pchBuffer (PCFIAR) - input 

A pointer to the caller-supplied buffer containing the element data. 


cchBytes (LONG) - input 

Length of caller-supplied buffer. 

ulFlags (ULONG) - input 

Specifies options for the operation. Contains 0 or the following flag: 

MMIO_CF_ENTRY_EXISTS 

Set only if the compound-file table of contents (CTOC) entry for this element already exists. 

rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

For this function a null pszE/ement/Vame , pchBuffer , or cchBytes is invalid. 

MMIOERR_READ_ONLY_FILE 

The RIFF compound file is opened as read-only. 

MMIO_CF_FAILURE 

The function failed. A call to mmioGetLastError may return: 

MMIOERRINTERNALSYSTEM 

The operation failed due to an internal system error. 


mmioCFAddElement - Remarks 


The compound-file table of contents (CTOC) entry for the element does not have to exist prior to the call. mmioCFAddElement adds the 
entry if it does not exist. The mmioCFAddElement function writes the element to the end of the compound-file resource-group (CGRP) 
chunk. The user's buffer contains the element data. 

This function is used when the element exists but is not contained in the RIFF compound file. If the element does not exist, use mmioOpen 
with the MMIO_CREATE flag to add a newly created element to the RIFF compound file. In that case the file name used with mmioOpen 
must contain the compound file and element name (that is, aaa.bnd+element). 

The user is not required to use mmioCFAddElement to add an element to a RIFF compound file. Flowever, one would need to replicate the 
following function that mmioCFAddElement provides. 

• Seek to the start of the RIFF compound file. 

■ Descend to the BND chunk. 

• Descend to the CGRP chunk. 

• Seek to the end of the CGRP. 

■ mmioWrite to write all of the data. 

• Ascend the CGRP to correct the size. 

■ Ascend the BND to correct the size. 

• If the CTOC already exists, call mmioCFChangeEntry to update the data offset and size of the element. 

■ If not, call mmioCFAddEntry to add the CTOC entry. 


mmioCFAddElement - Related Functions 


mmioCFCopy 


mmioCFAddElement - Example Code 


The following code illustrates how to add an element. 

HMMCF hmmc f 1 ; 

CHAR *pFileName; 

FOURCC fcctype; 

CHAR *pchBuf fer; 

USHORT cchBuf fer ; 

ULONG ulFlags; 

ULONG rc; 


strcpy ( pFileName, "myelement . f oo" ); 

fcctype = FOURCC_FOO; 

rc = mmioCFAddElement (hmmcfl , 

pFileName, 
fcctype, 
pchBuf fer , 
cchBuf fer , 
ulFlags) ; 

if (rc) 

/* error */ 
else 
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mmioCFAddEntry 


mmioCFAddEntry - Syntax 


This function adds an entry to the compound-file table of contents (CTOC) chunk of an open RIFF compound-file. Duplicate entries are not 


allowed. 


#def ine INCL_MMIOOS2 
#include <os2.h> 


HMMCF 

hmmcf; 

/* 

RIFF file handle. */ 

PMMCTOCENTRY 

pmmctocentry; 

/* 

Pointer to MMCTOCENTRY 

ULONG 

ulFlags; 

/* 

Flags. */ 

ULONG 

rc; 

/* 

Return codes. */ 


rc = mmioCFAddEntry (hmmcf , pmmctocentry, ulFlags) ; 


mmioCFAddEntry Parameter - hmmcf 


hmmcf (HMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. 


mmioCFAddEntry Parameter - pmmctocentry 


pmmctocentry (PMMCTOCENTRY) - input 

A pointer to a user-supplied CTOC structure containing the CTOC data. This structure is variable in size and the user must ensure 
enough memory has been allocated for it. 


mmioCFAddEntry Parameter - ulFlags 


ulFlags (ULONG) - input 

(Flags currently not used.) 


mmioCFAddEntry Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

The parameter passed was not correct. For this function, a pmmctocentry NULL is invalid. 


MMIOERR_READ_ONLY_FILE 

The RIFF compound-file is opened as read-only. 

MMIO_CF_FAILURE 

The function failed. A call to mmioGetLastError might return one of the following errors: 
MMIOERR_CF_DUPLICATE_SEEN 

The requested entry already exists. This means that the element name is already defined in 
another CTOC entry. 

MMIOERR_NO_CORE 

Not enough memory is available. 

MMIOERRINTERNALSYSTEM 

The operation failed due to an internal system error. 


mmioCFAddEntry - Parameters 


hmmcf (FIMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. 
pmmctocentry (PMMCTOCENTRY) - input 

A pointer to a user-supplied CTOC structure containing the CTOC data. This structure is variable in size and the user must ensure 
enough memory has been allocated for it. 

ulFlags (ULONG) - input 

(Flags currently not used.) 

rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

The parameter passed was not correct. For this function, a pmmctocentry NULL is invalid. 

MMIOERR_READ_ONLY_FILE 

The RIFF compound-file is opened as read-only. 

MMIO_CF_FAILURE 

The function failed. A call to mmioGetLastError might return one of the following errors: 
MMIOERR_CF_DUPLICATE_SEEN 

The requested entry already exists. This means that the element name is already defined in 
another CTOC entry. 

MMIOERR_NO_CORE 

Not enough memory is available. 

MMIOERRINTERNALSYSTEM 

The operation failed due to an internal system error. 


mmioCFAddEntry - Remarks 


The identifier for the entry is the element name, which is appended to the end of the MMCTOCENTRY structure passed in the 


pmmctocentry parameter. It is not case-sensitive. If mmioCFAddEntry expands the current number of entries past the number currently 
allocated, when a mmioCFCIose is called, the CTOC gets written following the CGRP chunk in the file. The mmioCFAddEntry function 
operates only on the CTOC in memory and does not do any expansion of the file itself. 


mmioCFAddEntry - Related Functions 


mmioCFChangeEntry 

mmioCFFindEntry 

mmioCFDeleteEntry 


mmioCFAddEntry - Example Code 


The following code illustrates how to add an entry. 

HMMCF hmmcfl; 

MMCTOCENTRY mmctocentry; 

ULONG ulFlags; 

ULONG rc; 


ulFlags = 0; 

rc = mmioCFAddEntry (hmmcfl , 

^mmctocentry, 
ulFlags) ; 

if (rc) 

/* error */ 
else 
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mmioCFChangeEntry 


mmioCFChangeEntry - Syntax 


This function modifies a compound-file table of contents (CTOC) entry in an open RIFF compound file. 


#def ine INCL_MMIOOS2 
ftinclude <os2.h> 


HMMCF 

hmmc f ; 

/* 

RIFF file handle. */ 

PMMCTOCENTRY 

pmmctocentry; 

/* 

Pointer to MMCTOCENTRY 

ULONG 

ulFlags; 

/* 

Flags. */ 

ULONG 

rc; 

/* 

Return codes. */ 


rc = mmioCFChangeEntry (hmmcf , pmmctocentry, 
ulFlags) ; 


mmioCFChangeEntry Parameter - hmmcf 


hmmcf (FIMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. 


mmioCFChangeEntry Parameter - pmmctocentry 


pmmctocentry (PMMCTOCENTRY) - input 

A pointer to the MMCTOCENTRY structure containing the modified CTOC data. This structure is variable in size and the user must 
ensure enough memory has been allocated for it. 


mmioCFChangeEntry Parameter - ulFlags 


ulFlags (ULONG) - input 

Specifies options for the operation. Contains none or the following flag: 


MMIO_CHANGEDELETED 

Allows a deleted CTOC entry to be changed. 


mmioCFChangeEntry Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 


MMIO_CF_SUCCESS 

If the function succeeds, 0 is returned. 


MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

The parameter passed was not correct. For this function, a pmmctocentry NULL is invalid. 

MMIOERR_READ_ONLY_FILE 

The RIFF compound-file is opened as read-only. 

MMIO_CF_FAILURE 

The function failed. The u/ErrorRet field of the MMIOINFO structure contains additional information as follows: 

MMIOERR_CF_ENTRY_NOT_FOUND 

The CTOC entry corresponding to the element was not found. 

MMIOERR_INTERNAL_SYSTEM 

The operation failed due to an internal system error. 


mmioCFChangeEntry - Parameters 


hmmcf (FIMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. 
pmmctocentry (PMMCTOCENTRY) - input 

A pointer to the MMCTOCENTRY structure containing the modified CTOC data. This structure is variable in size and the user must 
ensure enough memory has been allocated for it. 

ulFlags (ULONG) - input 

Specifies options for the operation. Contains none or the following flag: 

MMIO_CHANGEDELETED 

Allows a deleted CTOC entry to be changed. 

rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

The parameter passed was not correct. For this function, a pmmctocentry NULL is invalid. 

MMIOERR_READ_ONLY_FILE 

The RIFF compound-file is opened as read-only. 

MMIO_CF_FAILURE 

The function failed. The u/ErrorRet field of the MMIOINFO structure contains additional information as follows: 

MMIOERR_CF_ENTRY_NOT_FOUND 

The CTOC entry corresponding to the element was not found. 

MMIOERRINTERNALSYSTEM 

The operation failed due to an internal system error. 


mmioCFChangeEntry - Remarks 


The identifier for the entry is the element name, which is appended to the end of the MMCTOCENTRY structure passed in the 


pmmctocentry parameter. (The element name itself can not be modified.) mmioCFChangeEntry updates the compound-file CTOC entry 
with the information contained MMCTOCENTRY structure. If the compression technique is changed, the u/UncompressBytes field of the 
MMCTOCENTRY structure must also be changed. When the compression technique is NULL, the u/UncompressBytes field must be the 
size in bytes of the element when it is uncompressed. Consider calling mmioCFFindEntry to fill in the MMCTOCENTRY structure prior to 
calling this function. 


mmioCFChangeEntry - Related Functions 


mmioCFAddEntry 

mmioCFFindEntry 

mmioCFDeleteEntry 


mmioCFChangeEntry - Example Code 


The following code illustrates how to modify an entry. 

HMMCF hmmcfl; 

MMCTOCENTRY mmctocentry; 

ULONG ulFlags; 

ULONG rc; 


memset ( &mmctocentry, ' \0', sizeof (MMCTOCENTRY) ) ; 

rc = mmioCFChangeEntry ( hmmcfl, &mmctocentry , ulFlags) ; 

if (rc) 

/* error */ 
else 
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mmioCFCIose 


mmioCFCIose - Syntax 


This function closes a compound file that was opened by mmioCFOpen. 


#def ine 

INCL_MMIOOS2 



#include 

<os2 . h> 




HMMCF 

hmmc f ; 

/* 

Compound- file 

handle 

ULONG 

ulFlags; 

/* 

Reserved. */ 


ULONG 

rc; 

/* 

Return codes. 

*/ 


rc = mmioCFClose (hmmcf , ulFlags) ; 


mmioCFClose Parameter - hmmcf 


hmmcf (HMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. 


mmioCFClose Parameter - ulFlags 


ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioCFClose Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIO_CF_FAILURE 

The function failed. A call to mmioGetLastError might return one of the following errors: 

MMIOERR_CF_NON_BND_FILE 

Tried to close a non RIFF compound file. 

MMIOERR_CF_ELEMENTS_OPEN 

Compound-file elements are open. 

MMIOERRINTERNALSYSTEM 

The operation failed due to an internal system error. 


mmioCFClose - Parameters 


hmmcf (HMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. 

ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 

rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIO_CF_FAILURE 

The function failed. A call to mmioGetLastError might return one of the following errors: 

MMIOERR_CF_NON_BND_FILE 

Tried to close a non RIFF compound file. 

MMIOERR_CF_ELEMENTS_OPEN 

Compound-file elements are open. 

MMIOERRINTERNALSYSTEM 

The operation failed due to an internal system error. 


mmioCFCIose - Remarks 


This function decrements the usage count of the compound-file table of contents (CTOC) maintained in memory for this RIFF compound file. 
If the usage count drops to 0, the CTOC is written to disk, and the RIFF compound-file handle is closed. An mmioCFCIose operation fails if 
there are any open elements for this RIFF compound file. The user will get an error if mmioClose is used instead of mmioCFCIose when 
trying to close a RIFF compound file. 

If this is an Ex/tList close, all open elements are closed, and the mmioCFCIose operation is allowed. If the compound file was opened as 
read-only, the CTOC will not be rewritten. 

If the mmioCFCIose function fails and the user had modified compound-file-resource-group (CGRP) elements, the data stored on the file is 
inconsistent. To correct the problem, the user must create free file space and attempt to close again. 


mmioCFCIose - Related Functions 

• mmioCFOpen 


mmioCFCIose - Example Code 


The following code illustrates how to close a file. 


HMMCF hmmcf 1; 
ULONG ulFlags; 
ULONG rc; 


rc = mmioCFClose ( hmmcfl, ulFlags) ; 
if (rc) 

/* error */ 
else 
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mmioCFCompact 


mmioCFCompact - Syntax 


This function compacts the elements of a RIFF compound file. 


#def ine 

INCL_MMIOOS2 



#include 

<os2 . h> 



PSZ 

pszFileName ; 

/* 

RIFF file name. */ 

ULONG 

ulFlags; 

/* 

Reserved. */ 

ULONG 

rc; 

/* 

Return codes. */ 


rc = mmioCFCompact (pszFileName, ulFlags) ; 


mmioCFCompact Parameter - pszFileName 


pszFileName (PSZ) - input 

The name of the RIFF compound file to compact. 


mmioCFCompact Parameter - ulFlags 


ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioCFCompact Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The open failed. Possible reasons for failure include a nonexistent file name or an already open file. 

MMIOERRINVALIDFILENAME 

No file name was specified. 

MMIOERRINTERNALSYSTEM 

An internal system error has occurred. 

MMIOERR_NO_CORE 

The buffer cannot be allocated. 


mmioCFCompact - Parameters 


pszFileName (PSZ) - input 

The name of the RIFF compound file to compact. 

ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 

rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The open failed. Possible reasons for failure include a nonexistent file name or an already open file. 

MMIOERRINVALIDFILENAME 

No file name was specified. 

MMIOERRINTERNALSYSTEM 

An internal system error has occurred. 

MMIOERR_NO_CORE 

The buffer cannot be allocated. 


mmioCFCompact - Remarks 


This function is useful for writers of audio-enabling macros who use compound files in their implementation. 

The mmioCFCompact function does not use a compression algorithm to compact the compound file. It merely deletes elements in the 
CGRP whose u/MedType field of MMCTOCENTRY are marked as FOURCC_DEL and updates the u/MedType field to FOURCC_FREE. 
At the completion of the function, CTOC entries are sorted according to offset. Entries might not remain sorted if subsequent appends are 
made. 

The mmioCFCompact function compacts the file in place; that is, the function rewrites the file within the same buffer as the source to save 
memory. No original can be salvaged if an error occurs during compaction. If this behavior is unacceptable use mmioCFCopy. 

The mmioCFCopy function also compacts a file, but it rewrites the file to a specified target name. The target name cannot be the same as 
the source file name. Therefore, with this function you must delete the source file. 


mmioCFCompact - Related Functions 

• mmioCFCopy 


mmioCFCompact - Example Code 


The following code illustrates compacting a file with mmioCFCompact. 

PSZ pszFileName; 

ULONG ulFlags ; 

ULONG ulReturnCode; 

pszFileName = "SOUNDS . BND" ; 
ulFlags = OL; 

ulReturnCode = mmioCFCompact ( pszFileName, ulFlags ) ; 

if (ulReturnCode) 

/* error */ 

else 

/* success */ 
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mmioCFCopy 


mmioCFCopy - Syntax 


This function copies the compound-file table of contents (CTOC) and the compound-file resource group (CGRP) chunks from an open RIFF 
compound file to another RIFF compound file. The newly written compound-file resource group (CGRP) chunk will be compacted; that is, it 
will have no deleted elements. 


#def ine INCL_MMIOOS2 
ftinclude <os2.h> 


HMMCF 

hmmcfSource ; 

/* 

RIFF file handle. */ 

PSZ 

pszDestFileName; 

/* 

Pointer to destination file name. */ 

ULONG 

ulFlags; 

/* 

Reserved. */ 

ULONG 

rc; 

/* 

Return codes. */ 


rc = mmioCFCopy (hmmcf Source, pszDestFileName, 
ulFlags) ; 


mmioCFCopy Parameter - hmmcfSource 


hmmcfSource (PIMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. This is the source file to be copied. 


mmioCFCopy Parameter - pszDestFileName 


pszDestFileName (PSZ) - input 

The pointer to the name of the destination file. The RIFF compound file is copied to the destination file. 


mmioCFCopy Parameter - ulFlags 


ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioCFCopy Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

The file name was null or tried to copy the file to itself. 

MMIOERR_READ_ONLY_FILE 

The RIFF compound file is opened as read-only. 

MMIO_CF_FAILURE 

The operation failed due to an internal system error. A call to mmioGetLastError might return one of the following 
errors: 

MMIOERR_CF_ELEMENTS_OPEN 

Compound-file elements are open. 

MMIOERR_NO_CORE 

Not enough memory is available. 

MMIOERRINTERNALSYSTEM 

The operation failed due to an internal system error. 


mmioCFCopy - Parameters 


hmmcfSource (PIMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. This is the source file to be copied. 

pszDestFileName (PSZ) - input 

The pointer to the name of the destination file. The RIFF compound file is copied to the destination file. 

ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 

rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

The file name was null or tried to copy the file to itself. 

MMIOERR_READ_ONLY_FILE 

The RIFF compound file is opened as read-only. 

MMIO_CF_FAILURE 

The operation failed due to an internal system error. A call to mmioGetLastError might return one of the following 
errors: 

MMIOERR_CF_ELEMENTS_OPEN 

Compound-file elements are open. 

MMIOERR_NO_CORE 

Not enough memory is available. 


MMIOERR INTERNAL SYSTEM 


The operation failed due to an internal system error. 


mmioCFCopy - Remarks 


mmioCFCopy copies the CTOC and CGRP chunks of an open source RIFF compound file to the target file. Deleted elements are not copied 
to the new file. mmioCFCopy opens the target file (using mmioOpen with the MMIO_CREATE flag) and builds a RIFF BND header at the 
beginning of the file. The CTOC and CGRP chunks then are copied. Notice that it is invalid to copy the RIFF compound file to itself. Upon 
completion of the copy operation, the target file is closed and resides on the file system, while the source file is unaltered. The target file 
must not be opened before mmioCFCopy is called. 

As a note for performance considerations, the function either copies the entire CTOC and CGRP chunks in one single system buffer, or 
does a fixed page-size copy. The method used depends on the size of the RIFF compound file and is determined by the system. If the copy 
operation fails, the target file is deleted. 

If the target already exists, it is overwritten by the copy operation. 


mmioCFCopy - Related Functions 


mmioCFAddElement 


mmioCFCopy - Example Code 


The following code illustrates how to copy from a file. 

HMMCF hmmcf Source; 

PSZ pszDestFileName; 

ULONG ulFlags; 

ULONG rc; 


rc = mmioCFCopy ( hmmcfSource, pszDestFileName, ulFlags) ; 
if (rc) 

/* error */ 
else 
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mmioCFDeleteEntry 


mmioCFDeleteEntry - Syntax 


This function deletes a compound-file table of contents (CTOC) entry from an open RIFF compound file. 


#def ine INCL_MMIOOS2 
ftinclude <os2.h> 


HMMCF 

hmmc f ; 

/* 

RIFF file handle. */ 

PMMCTOCENTRY 

pmmctocentry; 

/* 

Pointer to MMCTOCENTRY data structure. */ 

ULONG 

ulFlags; 

/* 

Reserved. */ 

ULONG 

rc; 

/* 

Return codes. */ 


rc = mmioCFDeleteEntry (hmmcf, pmmctocentry, 
ulFlags) ; 


mmioCFDeleteEntry Parameter - hmmcf 


hmmcf (FIMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. 


mmioCFDeleteEntry Parameter - pmmctocentry 


pmmctocentry (PMMCTOCENTRY) - input 

A pointer to the MMCTOCENTRY data structure containing the RIFF compound-file element name. This structure is variable in size, 
and the user must ensure enough memory has been allocated for it. 


mmioCFDeleteEntry Parameter - ulFlags 


ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioCFDeleteEntry Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

For this function, a pszE/ement/Vame, pchBuffer, or cchBytes NULL is invalid. 

MMIOERR_READ_ONLY_FILE 

The RIFF compound file is opened as read-only. 

MMIO_CF_FAILURE 

The function failed. A call to mmioGetLastError might return one of the following errors: 

MMIOERR_CF_ENTRY_NOT_FOUND 

The CTOC entry corresponding to the element was not found. 

MMIOERRINTERNALSYSTEM 

The operation failed due to an internal system error. 


mmioCFDeleteEntry - Parameters 


hmmcf (FIMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. 
pmmctocentry (PMMCTOCENTRY) - input 

A pointer to the MMCTOCENTRY data structure containing the RIFF compound-file element name. This structure is variable in size, 
and the user must ensure enough memory has been allocated for it. 

ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 

rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

For this function, a pszE/ement/Vame, pchBuffer, or cchBytes NULL is invalid. 

MMIOERR_READ_ONLY_FILE 

The RIFF compound file is opened as read-only. 

MMIO_CF_FAILURE 

The function failed. A call to mmioGetLastError might return one of the following errors: 

MMIOERR_CF_ENTRY_NOT_FOUND 

The CTOC entry corresponding to the element was not found. 

MMIOERRINTERNALSYSTEM 

The operation failed due to an internal system error. 


mmioCFDeleteEntry - Remarks 


The identifier for the entry is the element name, which is appended to the end of the MMCTOCENTRY structure passed in the 
pmmctocentry parameter. The CTOC entry is marked as deleted by setting the u/MedType field to FOURCC_DEL. The actual element data 
remains in place. To remove data that was previously marked for deletion, use mmioCFCopy. The result will be a compressed file with all 
those elements marked for deletion physically removed. 


mmioCFDeleteEntry - Related Functions 


mmioCFAddEntry 

mmioCFChangeEntry 

mmioCFFindEntry 


mmioCFDeleteEntry - Example Code 


The following code illustrates how to delete an entry. 

HMMCF hmmcfl; 

MMCTOCENTRY &mmctocentry ; 

ULONG ulFlags; 

ULONG rc; 


memset ( &mmctocentry, ' \0', sizeof (MMCTOCENTRY) ) ; 

rc = mmioCFDeleteEntry ( hmmcfl, &mmctocentry , ulFlags) ; 

if (rc) 

/* error */ 
else 
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mmioCFFindEntry 


mmioCFFindEntry - Syntax 


This function finds a particular CTOC entry in an open RIFF compound file. 


#def ine INCL_MMIOOS2 
ftinclude <os2.h> 


HMMCF 

hmmc f ; 

/* 

RIFF file handle. */ 

PMMCTOCENTRY 

pmmctocentry; 

/* 

Pointer to MMCTOCENTRY. */ 

ULONG 

ulFlags; 

/* 

Flags. */ 

ULONG 

rc; 

/* 

Return codes. */ 


rc = mmioCFFindEntry (hmmcf, pmmctocentry , 
ulFlags) ; 


mmioCFFindEntry Parameter - hmmcf 


hmmcf (FIMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. 


mmioCFFindEntry Parameter - pmmctocentry 


pmmctocentry (PMMCTOCENTRY) - in/out 

A pointer to the MMCTOCENTRY structure containing the name of the RIFF compound-file element to search for. This structure is 
variable in size and the user must ensure enough memory has been allocated for it. Flags in u/F/ags can be set to specify that an 
element is to be searched for by some attribute other than name. 


mmioCFFindEntry Parameter - ulFlags 


ulFlags (ULONG) - input 

This parameter can be used to specify that an element is to be searched for by some attribute other than name. The 
MMIO_FINDFIRST and MMIO_FINDNEXT flags are mutually exclusive. An MMIOERR_CF_ENTRY_NOT_USED error is returned if 
a matching entry is not found or it MMIO_FINDNEXT was specified and no more entries match the search CTOC entry. 

The following flags are supported: 

MMIO_FINDFIRST 

Find the first entry in the CTOC table. 

MMIO_FINDNEXT 

Find the next entry in the CTOC table after the entry previously found and returned in the pmmctocentry 
parameter. The pmmctocentry parameter must contain the previous CTOC entry. Returns NULL if pmmctocentry 
refers to the last entry. 


MMIO_FINDDELETED 

Find an entry in the CTOC table that has been marked as deleted 
MMIO_FINDUNUSED 

Find an entry in the CTOC table that has been marked as unused. A default compound file contains 16 unused 
CTOC entries in the CTOC table. As each CTOC entry and element is added, one of these unused entries is used. 


mmioCFFindEntry Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

For this function a pszE/ement/Vame, pchBuffer, or cchBytes NULL is invalid. 

MMIOERR_READ_ONLY_FILE 

The RIFF compound-file is opened as read-only. 

MMIOERR_CF_ENTRY_NOT_FOUND 

System failed to find CTOC entry. 

MMIO_CF_FAILURE 

The function failed. A call to mmioGetLastError might return one of the following errors: 

MMIOERR_WRITE_ONLY_FILE 

File not opened in read mode. 

MMIOERRINTERNALSYSTEM 

The operation failed due to an internal system error. 


mmioCFFindEntry - Parameters 


hmmcf (FIMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. 
pmmctocentry (PMMCTOCENTRY) - in/out 

A pointer to the MMCTOCENTRY structure containing the name of the RIFF compound-file element to search for. This structure is 
variable in size and the user must ensure enough memory has been allocated for it. Flags in u/F/ags can be set to specify that an 
element is to be searched for by some attribute other than name. 

ulFlags (ULONG) - input 

This parameter can be used to specify that an element is to be searched for by some attribute other than name. The 
MMIO_FINDFIRST and MMIO_FINDNEXT flags are mutually exclusive. An MMIOERR_CF_ENTRY_NOT_USED error is returned if 
a matching entry is not found or if MMIO_FINDNEXT was specified and no more entries match the search CTOC entry. 

The following flags are supported: 

MMIO_FINDFIRST 

Find the first entry in the CTOC table. 

MMIO_FINDNEXT 

Find the next entry in the CTOC table after the entry previously found and returned in the pmmctocentry 


parameter. The pmmctocentry parameter must contain the previous CTOC entry. Returns NULL if pmmctocentry 
refers to the last entry. 

MMIO_FINDDELETED 

Find an entry in the CTOC table that has been marked as deleted 
MMIO_FINDUNUSED 

Find an entry in the CTOC table that has been marked as unused. A default compound file contains 16 unused 
CTOC entries in the CTOC table. As each CTOC entry and element is added, one of these unused entries is used. 

rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

For this function a pszE/ement/Vame, pchBuffer, or cchBytes NULL is invalid. 

MMIOERR_READ_ONLY_FILE 

The RIFF compound-file is opened as read-only. 

MMIOERR_CF_ENTRY_NOT_FOUND 

System failed to find CTOC entry. 

MMIO_CF_FAILURE 

The function failed. A call to mmioGetLastError might return one of the following errors: 

MMIOERR_WRITE_ONLY_FILE 

File not opened in read mode. 

MMIOERRINTERNALSYSTEM 

The operation failed due to an internal system error. 


mmioCFFindEntry - Remarks 


The search is not case-sensitive; the flags operate as follows: 

• MMIO_FINDFIRST and MMIO_FINDNEXT cannot be specified together. 

If an element is specified, it is ignored; if no element is specified, the flags operate as follows: 

• If MMIO_FINDFIRST is specified, the first non-deleted entry is returned. 

■ If MMIO_FINDFIRST and MMIO_FINDDELETED are specified, the first deleted element is returned. 

All other cases use the element name in the search, and the flags operate as follows: 

• If no flags are specified, the first non-deleted entry that matches the element name passed in is returned. 

• If MMIO_FINDNEXT is specified, the entry that matches the element name passed in is found. The first non-deleted entry 
following this entry is returned. 

• If MMIO_FINDDELETED is specified, the entry that matches the element name passed in is found. If the entry is marked 
deleted, it is returned. 

• If MMIO_FINDNEXT and MMIO_FINDDELETED are specified, the entry that matches the element name passed in is found. The 
element name passed in may refer to an existing or deleted entry. At this point, the next entry that is deleted is returned. 

If the function succeeds, the MMCTOCENTRY structure passed in the pmmctocentry parameter is filled in with information about the CTOC 
entry. The user can proceed through the CTOC entry list by using MMIO_FINDFIRST followed by a series of MMIO_FINDNEXT actions, 
using the information from the previous call. 


mmioCFFindEntry - Related Functions 


mmioCFAddEntry 

mmioCFChangeEntry 

mmioCFDeleteEntry 


mmioCFFindEntry - Example Code 

The following code illustrates how to find an entry. 


HMMCF hmmcfl; 

MMCTOCENTRY mmctocentry; 
ULONG ulFlags; 

ULONG rc; 


memset ( &mmctocentry, 1 \ 0 f , sizeof (MMCTOCENTRY) ) ; 
rc = mmioCFFindEntry ( hmmcfl, &mmctocentry , ulFlags) ; 
if (rc) 

/* error */ 
else 
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mmioCFGetlnfo 


mmioCFGetlnfo - Syntax 


This function retrieves the compound-file table of contents (CTOC) header of an open RIFF compound file. 


#def ine INCL_MMIOOS2 
#include <os2.h> 


HMMCF 


hmmc f ; 


/* RIFF file handle. */ 


PMMCFINFO 

pmmcfinfo; 

/* 

Pointer to MMCFINFO. */ 

ULONG 

cBytes; 

/* 

Buffer size. */ 

ULONG 

rc; 

/* 

Return codes. */ 


rc = mmioCFGetlnf o (hmmcf , pmmcfinfo, cBytes) ; 


mmioCFGetlnfo Parameter - hmmcf 


hmmcf (HMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. 


mmioCFGetlnfo Parameter - pmmcfinfo 


pmmcfinfo (PMMCFINFO) - in/out 

A pointer to the MMCFINFO data structure, which is filled with the CTOC header. This structure is variable in size, and the user must 
ensure enough memory has been allocated for it. 


mmioCFGetlnfo Parameter - cBytes 


cBytes (ULONG) - input 

Size of the buffer that the pmmcf/nfo parameter points to. This is the maximum number of bytes that will be copied. 


mmioCFGetlnfo Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure. If the function succeeds, the number of bytes copied is returned. A NULL is 
returned for a failure. Additional error information is stored in the u/ErrorRet field of MMIOINFO as follows: 

MMIOERRINVALIDPARAMETER 

The parameter passed was invalid. For this function, a NULL pmmcf/nfo is invalid. cBytes must be greater than 0. 

MMIOERR_WRITE_ONLY_FILE 

File not opened in read mode. 

MMIOERRINTERNALSYSTEM 

The operation failed due to an internal system error. 


mmioCFGetlnfo - Parameters 


hmmcf (HMMCF) - input 

A RIFF compound-file handle returned by mmioCFOpen. 
pmmcfinfo (PMMCFINFO) - in/out 

A pointer to the MMCFINFO data structure, which is filled with the CTOC header. This structure is variable in size, and the user must 
ensure enough memory has been allocated for it. 

cBytes (ULONG) - input 

Size of the buffer that the pmmcf/nfo parameter points to. This is the maximum number of bytes that will be copied, 
rc (ULONG) - returns 

Return codes indicating success or type of failure. If the function succeeds, the number of bytes copied is returned. A NULL is 
returned for a failure. Additional error information is stored in the u/ErrorRet field of MMIOINFO as follows: 

MMIOERRINVALIDPARAMETER 

The parameter passed was invalid. For this function, a NULL pmmcf/nfo is invalid. cBytes must be greater than 0. 

MMIOERR_WRITE_ONLY_FILE 

File not opened in read mode. 

MMIOERR_INTERNAL_SYSTEM 

The operation failed due to an internal system error. 


mmioCFGetlnfo - Remarks 


The information copied to the pmmcf/nfo parameter consists of an MMCFINFO structure followed by the variable-length arrays: 
au/ExHdrF/c/Usage , au/ExEntF/dUsage , and au/ExHdrF/e/d . 

To find out how large a buffer the user needs to allocate, call mmioCFGetlnfo with the cBytes equal to the size of a ULONG. This will return 
the first field of the CTOC header, which happens to be the size of the header. This size can be used as cBytes on the subsequent call. 


mmioCFGetlnfo - Related Functions 


mmioCFSetlnfo 


mmioCFGetlnfo - Example Code 


The following code illustrates how to retrieve information from a file. 

HMMCF hmmcf 1; 

MMCFINFO &mmcf inf o; 

ULONG cBytes; 

ULONG rc; 


memset ( &mmcf inf o, * \ 0 f , sizeof (MMCFINFO) ) ; 

rc = mmioCFGetlnfo ( hmmcfl, &mmcfinfo, (ULONG) sizeof (ULONG) ) ; 
if (rc ! = (ULONG) sizeof (ULONG) ) 
break; 
else 

cBytes = pmmcf inf o->ulHeaderSize; 
rc = mmioCFGetlnfo ( hmmcfl, mmcfinfo, cBytes); 


if (rc) 

/* error */ 
else 
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mmioCFOpen 


mmioCFOpen - Syntax 


This function opens a RIFF compound file by name. 


#def ine INCL_MMIOOS2 
#include <os2.h> 


PSZ 

pszFileName ; 

/* 

RIFF file name. */ 


PMMCFINFO 

pmmcfinfo; 

/* 

Pointer to MMCFINFO 

. */ 

PMMIOINFO 

pmmioinf o; 

/* 

Pointer to MMIOINFO 

. */ 

ULONG 

ulFlags; 

/* 

Flags. */ 


HMMCF 

hmmcf ; 

/* 

RIFF compound-file ! 

handle 


hmmcf = mmioCFOpen (pszFileName, pmmcfinfo, 
pmmioinfo, ulFlags) ; 


mmioCFOpen Parameter - pszFileName 


pszFileName (PSZ) - input 

The name of the RIFF compound file to open. 


mmioCFOpen Parameter - pmmcfinfo 


pmmcfinfo (PMMCFINFO) - input 

A pointer to the MMCFINFO data structure containing optional header information. It can be NULL. 


mmioCFOpen Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) - input 

A pointer to the MMIOINFO information structure containing optional open information that is passed to mmioOpen. It can be NULL. 


mmioCFOpen Parameter - ulFlags 


ulFlags (ULONG) - input 

Contains none or some of the following flags. The MMIO_READ, MMIO_WRITE, and MMIO_READWRITE flags are mutually 
exclusive. 

MMIO_READ 

Open the file for reading only. This is the default if MMIO_WRITE and MMIO_READWRITE are not specified. 

MMIO_WRITE 

Open the file for writing. A file cannot be read from if the file is opened in this mode. 

MMIO_READWRITE 

Open the file for both reading and writing. 

MMIO_EXCLUSIVE 

Open the file with exclusive mode, denying other processes both read and write access to the file. mmioCFOpen 
fails if the file has been opened in any other mode for read or write access, even by the current process. 

MMIO_DENYWRITE 

Open the file and deny other processes write access to the file. mmioCFOpen fails if the file has been opened by a 
compatible process or for write access by any other process. 

MMIO_DENYREAD 

Open the file and deny other processes read access to the file. mmioCFOpen fails if the file has been opened by a 
compatible process or for read access by any other process. 

MMIO_DENYNONE 

Open the file and deny other processes read access to the file. mmioCFOpen fails if the file has been opened by a 
compatible process or for read access by any other process. 


MMIO_CREATE 

Directs mmioCFOpen to create a new file. If the file already exists, it is truncated to 0 length, unless it is already 
opened. In that case, a handle (FIMMCF) to the RIFF compound file is returned. 


mmioCFOpen Return Value - hmmcf 


hmmcf (FIMMCF) - returns 

If the function succeeds, the handle to the RIFF compound file is returned. A NULL is returned if it fails. 


mmioCFOpen - Parameters 


pszFileName (PSZ) - input 

The name of the RIFF compound file to open. 

pmmcfinfo (PMMCFINFO) - input 

A pointer to the MMCFINFO data structure containing optional header information. It can be NULL, 
pmmioinfo (PMMIOINFO) - input 

A pointer to the MMIOINFO information structure containing optional open information that is passed to mmioOpen. It can be NULL. 
ulFlags (ULONG) - input 

Contains none or some of the following flags. The MMIO_READ, MMIO_WRITE, and MMIO_READWRITE flags are mutually 
exclusive. 

MMIO_READ 

Open the file for reading only. This is the default if MMIO_WRITE and MMIO_READWRITE are not specified. 

MMIO_WRITE 

Open the file for writing. A file cannot be read from if the file is opened in this mode. 

MMIO_READWRITE 

Open the file for both reading and writing. 

MMIO_EXCLUSIVE 

Open the file with exclusive mode, denying other processes both read and write access to the file. mmioCFOpen 
fails if the file has been opened in any other mode for read or write access, even by the current process. 

MMIO_DENYWRITE 

Open the file and deny other processes write access to the file. mmioCFOpen fails if the file has been opened by a 
compatible process or for write access by any other process. 

MMIO_DENYREAD 

Open the file and deny other processes read access to the file. mmioCFOpen fails if the file has been opened by a 
compatible process or for read access by any other process. 

MMIO_DENYNONE 

Open the file and deny other processes read access to the file. mmioCFOpen fails if the file has been opened by a 
compatible process or for read access by any other process. 


MMIO_CREATE 

Directs mmioCFOpen to create a new file. If the file already exists, it is truncated to 0 length, unless it is already 
opened. In that case, a handle (FIMMCF) to the RIFF compound file is returned. 

hmmcf (FIMMCF) - returns 

If the function succeeds, the handle to the RIFF compound file is returned. A NULL is returned if it fails. 


mmioCFOpen - Remarks 


This function will either construct a compound-file table of contents (CTOC) in memory for this compound file or give the caller access to a 
CTOC that already exists in memory for this compound file. Only one CTOC for a particular compound file is maintained in memory at any 
given time. This CTOC is shared by any process that needs access to the file. 

This function will determine if the CTOC for this compound file is being maintained in memory. If so, the access and sharing modes are 
checked to ensure that an open operation is allowed. The existing handle (FIMMCF) for the CTOC is returned to the caller. If the file had not 
been previously opened, this function will construct a CTOC in memory for this file. If the name is not pointing to a valid BND file, an error is 
returned. 

The RIFF compound-file name cannot contain a + or [ because they are used to express elements of compound files. 


The access and sharing flags are maintained only within the set of compound-file functions. If the RIFF compound file or elements are 
accessed without using the compound-file calls, the access and sharing modes are unpredictable. An mmioOpen operation with a fully 
qualified element name is considered a compound-file call, because it internally calls mmioCFOpen; thus the flags are predictable in that 
case. 

Access and sharing modes are supported for compound files. Flowever, these modes are enforced only within the MMIO services 
compound-file functions and the mmioOpen of compound-file elements. The sharing modes work as in the base operating system except 
that elements ignore the sharing mode of the RIFF compound file. Elements do obey the access modes of the RIFF compound file. 

Elements can be opened and used from the compound file by sending the element name that is stored in the CTOC to the mmioOpen 
function. 

The FOURCC of FOURCC_BND should be used only for the element and not the compound file itself. That is, do not specify 
FOURCC_BND when using mmioCFOpen. 


mmioCFOpen - Related Functions 


mmioCFCIose 


mmioCFOpen - Example Code 


The following code illustrates how to open a file. 

HMMCF hmmcfl; 

MMCFINFO mmcfinfo; 

MMIOINFO mmioinfo; 

ULONG ulFlags; 


memset ( &mmcfinfo, * \ 0 * , sizeof (MMCFINFO) ) ; 
memset ( &mmioinfo, * \ 0 * , sizeof (MMIOINFO) ) ; 
strcpy ( pFileName, "myf ile .bnd" ); 
ulFlags = OL; 

hmmcfl = mmioCFOpen ( pFileName, &mmcfinfo, &mmioinfo, ulFlags) 
if (Ihmmcfl) 

/* error */ 
else 
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mmioCFSetlnfo 


mmioCFSetlnfo - Syntax 


This function modifies information that is stored in the compound-file table of contents (CTOC) header of an open RIFF compound file. 


#def ine INCL_MMIOOS2 
ftinclude <os2.h> 


HMMCF 

hmmcf; 

/* 

RIFF file handle. */ 

PMMCFINFO 

pmmcfinfo; 

/* 

Pointer to MMCFINFO. */ 

ULONG 

cBytes; 

/* 

Max # of bytes. */ 

ULONG 

rc; 

/* 

Return codes. */ 


rc = mmioCFSetlnfo (hmmcf, pmmcfinfo, cBytes) ; 


mmioCFSetlnfo Parameter - hmmcf 


hmmcf (FIMMCF) - input 

A pointer to a user-supplied buffer that contains the modified CTOC header. A RIFF compound-file handle is returned by 
mmioCFOpen. 


mmioCFSetlnfo Parameter - pmmcfinfo 


pmmcfinfo (PMMCFINFO) - input 

A pointer to the MMCFINFO data structure that contains the modified CTOC header. This buffer was filled in by mmioCFGetlnfo and 
then modified by the user. 


mmioCFSetlnfo Parameter - cBytes 


cBytes (ULONG) - input 

Size of the buffer that the pmmcf/nfo parameter points to. This is the maximum number of bytes that will be copied. 


mmioCFSetlnfo Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure. If the function succeeds, the number of bytes copied is returned. A NULL is 
returned for a failure. A call to mmioGetLastError might return one of the following errors: 

MMIOERRINVALIDPARAMETER 

For this function, a NULL pmmcf/nfo is invalid. cBytes must be greater than 0. 

MMIOERR_READ_ONLY_FILE 

File not opened in write mode. 

MMIOERR_INTERNAL_SYSTEM 

The operation failed due to an internal system error. 


mmioCFSetlnfo - Parameters 


hmmcf (FIMMCF) - input 

A pointer to a user-supplied buffer that contains the modified CTOC header. A RIFF compound-file handle is returned by 
mmioCFOpen. 

pmmcfinfo (PMMCFINFO) - input 

A pointer to the MMCFINFO data structure that contains the modified CTOC header. This buffer was filled in by mmioCFGetlnfo and 
then modified by the user. 

cBytes (ULONG) - input 

Size of the buffer that the pmmcf/nfo parameter points to. This is the maximum number of bytes that will be copied, 
rc (ULONG) - returns 

Return codes indicating success or type of failure. If the function succeeds, the number of bytes copied is returned. A NULL is 
returned for a failure. A call to mmioGetLastError might return one of the following errors: 

MMIOERRINVALIDPARAMETER 

For this function, a NULL pmmcf/nfo is invalid. cBytes must be greater than 0. 

MMIOERR_READ_ONLY_FILE 

File not opened in write mode. 

MMIOERR_INTERNAL_SYSTEM 

The operation failed due to an internal system error. 


mmioCFSetlnfo - Remarks 


The only data that should be modified by the user is au/ExHdrF/dUsage and au/ExHc/rFfe/d fields appended to the end of the MMIOINFO 
structure passed in the pmmcfinfo parameter. 


mmioCFSetlnfo - Related Functions 


mmioCFGetlnfo 


mmioCFSetlnfo - Example Code 


The following code illustrates how to modify information in a file. 

HMMCF hmmcfl; 

MMCFINFO &mmcf inf o; 

ULONG cBytes; 

ULONG rc; 


memset ( &mmcf inf o, * \ 0 1 , sizeof (MMCFINFO) ) ; 

rc = mmioCFGetlnf o ( hmmcfl, &mmcfinfo, (ULONG) sizeof (ULONG) ) ; 
if (rc ! = (ULONG) sizeof (ULONG) ) 
break; 
else 

cBytes = pmmcf inf o->ulHeaderSize; 


rc = mmioCFSetlnfo ( hmmcfl, &mmcfinfo, cBytes); 
if (rc) 

/* error */ 
else 
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mmioClose 


mmioClose - Syntax 


This function closes a file that was opened by mmioOpen. 


#def ine 

INCL_MMIOOS2 



#include 

<os2 . h> 



HMMIO 

hmmio; 

/* 

Open file handle 

USHORT 

usFlags; 

/* 

Flags. */ 

USHORT 

rc; 

/* 

Return codes. */ 


rc = mmioClose (hmmio, usFlags) ; 


mmioClose Parameter - hmmio 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


mmioClose Parameter - usFlags 


usFlags (USHORT) - input 

Contains nothing or the following flag: 

MMIO_FHOPEN 

This flag is used to tell the I/O to not close the file or files of type FOURCC_DOS. This allows an HMMIO instance 
to be closed in cases where a DOS file handle was provided to the I/O procedure on an mmioOpen call. 


mmioClose Return Value - rc 


rc (USHORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not correct. 

MMIOERR_CANNOTWRITE 

The I/O buffer needs to be written to disk but disk space is lacking. 
MMIOERR_WRITE_FAILED 

Unable to write the buffer to disk. Possible hardware problem. 

MMIO_WARNING 

The file was closed, but the lOProc might be expecting additional data. 


mmioClose - Parameters 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


usFlags (USHORT) - input 

Contains nothing or the following flag: 


MMIO_FHOPEN 


This flag is used to tell the I/O to not close the file or files of type FOURCC_DOS. This allows an FIMMIO instance 
to be closed in cases where a DOS file handle was provided to the I/O procedure on an mmioOpen call. 

rc (USFIORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not correct. 

MMIOERR_CANNOTWRITE 

The I/O buffer needs to be written to disk but disk space is lacking. 

MMIOERR_WRITE_FAILED 

Unable to write the buffer to disk. Possible hardware problem. 

MMIOJ/VARNING 

The file was closed, but the lOProc might be expecting additional data. 


mmioClose - Remarks 


A buffer is automatically emptied when you close a file by calling mmioClose. 


mmioClose - Related Functions 


mmioOpen 

mmioRead 

mmioSeek 

mmioWrite 


mmioClose - Example Code 


The following code illustrates how to close a file. 

HMMIO hmmiol; 

USHORT usFlags; 

USHORT rc; 


usFlags = 0; 

rc = mmioClose (hmmiol , usFlags); 
if (rc) 

/* error */ 
else 
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mmioCreateChunk 


mmioCreateChunk - Syntax 


This function creates a chunk in a RIFF file that was opened by mmioOpen. 


#def ine INCL_MMIOOS2 
ftinclude <os2.h> 


HMMIO 

hmmio; 

/* 

PMMCKINFO 

pckinfo; 

/* 

USHORT 

usFlags; 

/* 

USHORT 

rc; 

/* 


Open file handle. */ 
Pointer to MMCKINFO . */ 
Flags. */ 

Return codes. */ 


rc = mmioCreateChunk (hmmio, pckinfo, usFlags); 


mmioCreateChunk Parameter - hmmio 


hmmio (FIMMIO) - input 

The open file handle returned by mmioOpen. 


mmioCreateChunk Parameter - pckinfo 


pckinfo (PMMCKINFO) - input 

A pointer to an MMCKINFO data structure that is to be filled in as follows: 
ckid 

Must be the chunk ID of the chunk to create. If usF/ags includes MMIO_CREATERIFF or MMIO_CREATELIST, 
this field will be filled in by mmioCreateChunk. 

ckSize 

Must be the size of the data portion of the chunk, including the form type or list type (if any) but not including the 


8-byte chunk header or the terminating null (if any). If this value is not correct when mmioAscend is called to mark 
the end of the chunk, then mmioAscend will seek back and correct the chunk size. 


fccType 

Must contain the form type or list type, respectively, if usF/ags contains MMIO_CREATERIFF or 
MMIO_CREATELIST. 


uIDataOffset 

This field will be filled in on the return from mmioCreateChunk. It will contain the file offset of the beginning of the 
data portion of the chunk. 


ulFlags 

This field will be filled in on the return from this mmioCreateChunk. It will contain the MMIO_DIRTY flag to indicate 
this chunk was created with mmioCreateChunk. 


mmioCreateChunk Parameter - usFlags 


usFlags (USFIORT) - input 

Contains none or one of the following flags: 

MMIO_CREATERIFF 

Create a chunk with an ID {ck/d field) of RIFF and a form type in the fccType field. 
MMIO_CREATELIST 

Create a chunk with an ID {ckic/ field) of LIST and a list type in the fccType field. 


mmioCreateChunk Return Value - rc 


rc (USFIORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERR INVALID HANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

The parameter passed was not valid. 

MMIOERR_CANNOTWRITE 

The I/O buffer needs to be written to disk but disk space is lacking. 


mmioCreateChunk - Parameters 


hmmio (FIMMIO) - input 

The open file handle returned by mmioOpen. 

pckinfo (PMMCKINFO) - input 

A pointer to an MMCKINFO data structure that is to be filled in as follows: 


ckid 


Must be the chunk ID of the chunk to create. If usF/ags includes MMIO_CREATERIFF or MMIO_CREATELIST, 
this field will be filled in by mmioCreateChunk. 


ckSize 

Must be the size of the data portion of the chunk, including the form type or list type (if any) but not including the 
8-byte chunk header or the terminating null (if any). If this value is not correct when mmioAscend is called to mark 
the end of the chunk, then mmioAscend will seek back and correct the chunk size. 

fccType 

Must contain the form type or list type, respectively, if usF/ags contains MMIO_CREATERIFF or 
MMIO_CREATELIST. 

uIDataOffset 

This field will be filled in on the return from mmioCreateChunk. It will contain the file offset of the beginning of the 
data portion of the chunk. 

ulFlags 

This field will be filled in on the return from this mmioCreateChunk. It will contain the MMIO_DIRTY flag to indicate 
this chunk was created with mmioCreateChunk. 

usFlags (USFIORT) - input 

Contains none or one of the following flags: 

MMIO_CREATERIFF 

Create a chunk with an ID {ckid field) of RIFF and a form type in the fccType field. 

MMIO_CREATELIST 

Create a chunk with an ID (ckid field) of LIST and a list type in the fccType field. 


rc (USFIORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

The parameter passed was not valid. 

MMIOERR_CANNOTWRITE 

The I/O buffer needs to be written to disk but disk space is lacking. 


mmioCreateChunk - Remarks 


mmioCreateChunk creates a new chunk; that is, it writes a chunk header starting at the current file position and descends into the chunk. 
The chunk ID is copied from the ckid field of the provided MMCKINFO structure. Call mmioAscend after the chunk data has been written. 
The ckSize field is assumed to be a proposed chunk size, if it turns out to be correct; that is, if you write that much data into the chunk 
before calling mmioAscend to end the chunk, mmioAscend will not have to seek back and correct the chunk header. 


mmioCreateChunk - Related Functions 


mmioAscend 

mmioDescend 

mmioFOURCC 

mmioStringToFOURCC 


mmioCreateChunk - Example Code 


The following code illustrates how to create a chunk in a file. 

HMMIO hmmiol; 

MMCKINFO mmckinf o; 

USHORT usFlags; 

USHORT rc; 


memset ( &mmckinfo, ' \0', sizeof (MMCKINFO) ); 
mmckinf o . ckid = FOURCC_WAVE; 
mmckinf o . ckSize = 1000; 
usFlags |= MMIO_CREATERIFF ; 

rc = mmioCreateChunk (hmmiol , &mmckinfo, usFlags); 

if (rc) 

/* error */ 
else 
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mmioDescend 


mmioDescend - Syntax 


This function descends into a chunk beginning at the current file position, or searches for a specified chunk. 


#def ine INCL_MMIOOS2 
ftinclude <os2.h> 


HMMIO 

hmmio; 

/* 

Open file handle. */ 


PMMCKINFO 

pckinf o; 

/* 

Pointer to MMCKINFO. 

*/ 

PMMCKINFO 

pckinf oParent ; 

/* 

Pointer to MMCKINFO. 

*/ 

USHORT 

usFlags; 

/* 

Flags. */ 


USHORT 

rc; 

/* 

Return codes. */ 



rc = mmioDescend (hmmio, pckinfo, pckinf oParent , 
usFlags) ; 


mmioDescend Parameter - hmmio 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


mmioDescend Parameter - pckinfo 


pckinfo (PMMCKINFO) - input 

A pointer to the caller-supplied MMCKINFO structure that is to be filled in as follows: 


ckid 

ckSize 

fccType 

uIDataOffset 

ulFlags 


Set to the chunk ID of the chunk. 

Set to the size of the data portion of the chunk, including the form type or list type (if any) but not including the 
8-byte chunk header or the terminating null (which is present only if chunk size is odd). 

The form type for RIFF chunks, the list type for LIST types, or a NULL value. 

The file offset of the beginning of the data portion of the chunk, which begins after the 8-byte chunk header. If the 
chunk is a LIST chunk or a RIFF chunk, then this field must contain the offset of the list type or form type. 

Contains other information about the chunk. Currently, mmioDescend zeros this field. 


mmioDescend Parameter - pckinfoParent 


pckinfoParent (PMMCKINFO) - input 

Specifies a pointer to the MMCKINFO data structure, which is an optional caller-supplied structure that refers to the parent of the 
chunk that is being searched for. 

A parent of a chunk is the enclosing chunk - only RIFF and LIST chunks can be parents. If pckinfoParent is given, it is assumed that 
pckinfoParent was filled in when mmioDescend was called to descend into the parent chunk, and mmioDescend will only search for 
and descend into a chunk within the parent chunk. If pckinfoParent is NULL, this restriction is not imposed. mmioDescend checks 
only if a chunk is past the end of a given parent chunk, not before the beginning of the parent chunk. Also, mmioDescend checks only 
if the beginning of a chunk is past the end of the parent chunk. 


mmioDescend Parameter - usFlags 


usFlags (USHORT) - input 

Contains 0 or one of the following flags. If none of these flags are specified, mmioDescend descends into the chunk that starts at the 
current file position. 


MMIO_FINDCHUNK 

Search for a chunk with a specific ID. The ckicf field of MMCKINFO passed in on the pck/nfo parameter should 
contain the ID of the chunk to search for when mmioDescend is called. 


MMIO_FINDRIFF 

Search for a chunk with an ID of FOURCC_RIFF and with a specific form type. The fccType field of MMCKINFO 
passed in on the pck/nfo parameter contains the form type of the RIFF chunk to search for when mmioDescend is 
called. 

MMIO_FINDLIST 

Search for a chunk with an ID of FOURCCJJST and with a specific list type. The fccType field of MMCKINFO 
passed in on the pck/nfo parameter contains the list type of the LIST chunk to search for when mmioDescend is 
called. 


mmioDescend Return Value - rc 


rc (USFIORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not correct. 

MMIOERRINVALIDPARAMETER 

A parameter passed was not correct. 

MMIOERR_CHUNKNOTFOUND 

The end of the file (or the end of the parent chunk, if given) is reached before the desired chunk is found. 


mmioDescend - Parameters 


hmmio (FIMMIO) - input 

The open file handle returned by mmioOpen. 


pckinfo (PMMCKINFO) - input 

A pointer to the caller-supplied MMCKINFO structure that is to be filled in as follows: 


ckid 

ckSize 

fccType 

uIDataOffset 

ulFlags 


Set to the chunk ID of the chunk. 

Set to the size of the data portion of the chunk, including the form type or list type (if any) but not including the 
8-byte chunk header or the terminating null (which is present only if chunk size is odd). 

The form type for RIFF chunks, the list type for LIST types, or a NULL value. 

The file offset of the beginning of the data portion of the chunk, which begins after the 8-byte chunk header. If the 
chunk is a LIST chunk or a RIFF chunk, then this field must contain the offset of the list type or form type. 

Contains other information about the chunk. Currently, mmioDescend zeros this field. 


pckinfoParent (PMMCKINFO) - input 

Specifies a pointer to the MMCKINFO data structure, which is an optional caller-supplied structure that refers to the parent of the 
chunk that is being searched for. 


A parent of a chunk is the enclosing chunk - only RIFF and LIST chunks can be parents. If pck/nfoParent is given, it is assumed that 


pck/nfoParent was filled in when mmioDescend was called to descend into the parent chunk, and mmioDescend will only search for 
and descend into a chunk within the parent chunk. If pck/nfoParent is NULL, this restriction is not imposed. mmioDescend checks 
only if a chunk is past the end of a given parent chunk, not before the beginning of the parent chunk. Also, mmioDescend checks only 
if the beginning of a chunk is past the end of the parent chunk. 

usFlags (USHORT) - input 

Contains 0 or one of the following flags. If none of these flags are specified, mmioDescend descends into the chunk that starts at the 
current file position. 

MMIO_FINDCHUNK 

Search for a chunk with a specific ID. The ckid field of MMCKINFO passed in on the pck/nfo parameter should 
contain the ID of the chunk to search for when mmioDescend is called. 

MMIO_FINDRIFF 

Search for a chunk with an ID of FOURCC_RIFF and with a specific form type. The fccType field of MMCKINFO 
passed in on the pck/nfo parameter contains the form type of the RIFF chunk to search for when mmioDescend is 
called. 

MMIO_FINDLIST 

Search for a chunk with an ID of FOURCCJJST and with a specific list type. The fccType field of MMCKINFO 
passed in on the pck/nfo parameter contains the list type of the LIST chunk to search for when mmioDescend is 
called. 

rc (USFIORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not correct. 

MMIOERRINVALIDPARAMETER 

A parameter passed was not correct. 

MMIOERR_CHUNKNOTFOUND 

The end of the file (or the end of the parent chunk, if given) is reached before the desired chunk is found. 


mmioDescend - Remarks 


A RIFF chunk consists of a four-byte chunk ID ck/d (type FOURCC), followed by a four-byte chunk size, ckS/'ze (type ULONG), followed by 
the data portion of the chunk, followed by a 0 pad byte if ckS/'ze is odd. If ckid is FOURCC_RIFF or FOURCC_LIST, then the first four 
bytes of the data portion of the chunk are a form type or list type, respectively. ckS/'ze is the size of the chunk data, not including ck/d or 
ckS/'ze or the pad byte (if any), but including the form type or list type (if present). 

When mmioDescend is called, it assumes that the current file position is the beginning of a chunk header. If pck/nfoParent is given, 
mmioDescend assumes that the current file position is within pck/nfoParent (a RIFF to LIST chunk). If mmioDescend succeeds, the current 
file position will be either just after the form type or list type (1 2 bytes from the beginning of the chunk ID) if the chunk ID is FOURCC_RIFF 
or FOURCC_LIST, or the start of the data portion of the chunk (8 bytes from the beginning of the chunk ID). 

For efficiency of RIFF I/O, it is recommended that the f/mm/'o parameter be set up for buffered I/O. Note that the constants, FOURCC_RIFF 
and FOURCC_LIST, are defined to be the four-character codes, RIFF and LIST, respectively. 


mmioDescend - Related Functions 


mmioAscend 

mmioCreateChunk 

mmioFOURCC 

mmioStringToFOURCC 


mmioDescend - Example Code 


The following code illustrates how to descend into a chunk of a file. 

HMMIO hmmiol; 

MMCKINFO mmckinf o; 

USHORT usFlags = 0; 

USHORT rc; 


memset ( &mmckinfo, ' \0', sizeof (MMCKINFO) ); 
usFlags |= MMIO_FINDRIFF ; 
mmckinf o . ckid = FOURCC_WAVE; 

rc = mmioDescend (hmmiol , &mmckinfo, usFlags); 
if (rc) 

/* error */ 
else 


mmioDescend - Topics 
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mmioDetermineSSIOProc 


mmioDetermineSSIOProc - Syntax 


This function determines the storage system of the media data object. 


#def ine INCL_MMIOOS2 
#include <os2.h> 


PSZ 

pszFileName; 

/* 

PMMIOINFO 

pmmioinf o; 

/* 

PFOURCC 

pfccStorageSystem; 

/* 

PSZ 

pszParsedRemainder; 

/* 

ULONG 

rc; 

/* 


Media object file name. */ 

Pointer to MMIOINFO. */ 

Pointer to the FOURCC . */ 

Pointer to the parsed file name. */ 
Return codes. */ 


rc = mmioDetermineSSIOProc (pszFileName, pmmioinfo, 
pf ccStorageSystem, pszParsedRemainder ) ; 


mmioDetermineSSIOProc Parameter - pszFileName 


pszFileName (PSZ) - input 

The file name of the media object. This parameter can be NULL. 


mmioDetermineSSIOProc Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) - input 

A pointer to a MMIOINFO data structure that might contain additional data. Normally this is NULL, but is needed for compound-file 
elements that are not completely valid. 


mmioDetermineSSIOProc Parameter - pfccStorageSystem 


pfccStorageSystem (PFOURCC) - in/out 

Pointer to the FOURCC of the storage system that is returned when successfully completed. 


mmioDetermineSSIOProc Parameter - pszParsedRemainder 


pszParsedRemainder (PSZ) - in/out 

Pointer to the parsed file name that is returned when successfully completed. 


mmioDetermineSSIOProc Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure. For information about DOS File errors, see u/ErrorRet in MMIOINFO. 
MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

Unable to determine the FOURCC of the lOProc. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 


mmioDetermineSSIOProc - Parameters 


pszFileName (PSZ) - input 

The file name of the media object. This parameter can be NULL, 
pmmioinfo (PMMIOINFO) - input 

A pointer to a MMIOINFO data structure that might contain additional data. Normally this is NULL, but is needed for compound-file 
elements that are not completely valid. 

pfccStorageSystem (PFOURCC) - in/out 

Pointer to the FOURCC of the storage system that is returned when successfully completed. 

pszParsedRemainder (PSZ) - in/out 

Pointer to the parsed file name that is returned when successfully completed, 
rc (ULONG) - returns 

Return codes indicating success or type of failure. For information about DOS File errors, see u/ErrorPet in MMIOINFO. 
MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

Unable to determine the FOURCC of the lOProc. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 


mmioDetermineSSIOProc - Remarks 


mmioDetermineSSIOProc processes the MMIOINFO data first to check for a storage system I/O procedure specified in the fccCh//c//OProc 
field. If it is not NULL, the fccCh/Zd/OProc is returned as the storage system FOURCC. Otherwise, the file name is parsed for a separator 
character; if one is found, the extension is converted to the storage system FOURCC. In this case, mmioDetermineSSIOProc returns the 
parsed string that consists of those characters following the separator character. The name is parsed from left to right. 


mmioDetermineSSIOProc - Related Functions 


mmioldentifyStorageSystem 

mmioldentifyFile 


mmioDetermineSSIOProc - Example Code 


The following code illustrates how to determine the storage system of a data object. 

MMIOINFO mmioinfo; 

FOURCC fccType; 

PSZ pszParsedFileName; 


ULONG rc; 


rc = mmioDetermineSSIOProc ( "DAN . BND+SUE . WAV" , 

&mmioinf o, 

&f ccType, 

pszParsedFileName) ; 

if (rc) 

/* error */ 
else 


mmioDetermineSSIOProc - Topics 
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mmioFindElement 


mmioFindElement - Syntax 


This function enumerates the entries of a compound file. mmioFindElement is a 32-bit function that is also provided as a 16-bit entry point. 


#def ine INCL_MACHDR 
#include <os2.h> 


ULONG 

ulCode; 

/* 

Enumeration code. */ 


PSZ 

pszElement ; 

/* 

Pointer to element name . 

*/ 

ULONG 

ulElementLen; 

/* 

Length of element buffer. 

. */ 

PSZ 

pszFile ; 

/* 

Pointer to compound-file 

name 

ULONG 

ulReserved; 

/* 

Reserved. */ 


ULONG 

rc; 

/* 

Return codes. */ 



rc = mmioFindElement (ulCode, pszElement, ulElementLen, 
pszFile, ulReserved) ; 


mmioFindElement Parameter - ulCode 


ulCode (ULONG) - input 

The following flags are used to control the find operation: 

MMIO_FE_FINDFIRST 

Find the first element in the specified compound file. 

MMIO_FE_FINDNEXT 

Find the next element in the specified compound file. 

MMIO_FE_FINDELEMENT 

Search for an element in the specified compound file. MMIO_FE_FINDELEMENT supersedes a 
MMIO_FE_FINDFIRST/MMIO_FE_FINDNEXT search on the same file. 

MMIO_FE_FINDEND 

Complete the search of a compound file. MMIO_FE_FINDEND is called after MMIO_FE_FINDELEMENT, 
MMIO_FE_FINDNEXT, or MMIO_FE_FINDFIRST. 


mmioFindElement Parameter - pszElement 


pszElement (PSZ) - in/out 

Pointer to a compound-file element name. 


mmioFindElement Parameter - ulElementLen 


ulElementLen (ULONG) - input 

Length of the buffer the pszE/ement points to. 


mmioFindElement Parameter - pszFile 


pszFile (PSZ) - input 

Pointer to a RIFF compound-file name. This parameter should contain just the name of the compound file and not include the 
element name specification. 


mmioFindElement Parameter - ulReserved 


ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioFindElement Return Value - rc 


rc (ULONG) - returns 

Return code indicating success or type of failure: 
MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERR_CF_ENTRY_NOT_FOUND 

The element cannot be found. 

MMIOERRINVALIDPARAMETER 

If any parameter is missing. 

ERRORJNVALIDPARAMETER 

If u/Reser\zecT\s not zero. 

ERROR_BUFFER_OVERFLOW 

Element name is longer than u/E/ementLen . 


mmioFindElement - Parameters 


ulCode (ULONG) - input 

The following flags are used to control the find operation: 

MMIO_FE_FINDFIRST 

Find the first element in the specified compound file. 

MMIO_FE_FINDNEXT 

Find the next element in the specified compound file. 

MMIO_FE_FINDELEMENT 

Search for an element in the specified compound file. MMIO_FE_FINDELEMENT supersedes a 
MMIO_FE_FINDFIRST/MMIO_FE_FINDNEXT search on the same file. 

MMIO_FE_FINDEND 

Complete the search of a compound file. MMIO_FE_FINDEND is called after MMIO_FE_FINDELEMENT, 
MMIO_FE_FINDNEXT, or MMIO_FE_FINDFIRST. 

pszElement (PSZ) - in/out 

Pointer to a compound-file element name. 

ulElementLen (ULONG) - input 

Length of the buffer the pszE/ement points to. 

pszFile (PSZ) - input 

Pointer to a RIFF compound-file name. This parameter should contain just the name of the compound file and not include the 
element name specification. 

ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 

rc (ULONG) - returns 

Return code indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERR_CF_ENTRY_NOT_FOUND 

The element cannot be found. 

MMIOERRINVALIDPARAMETER 

If any parameter is missing. 


ERRORJNVALIDPARAMETER 

If u/Resen/ed is not zero. 

ERROR_BUFFER_OVERFLOW 

Element name is longer than u/E/ementLen . 


mmioFindElement - Remarks 


The mmioFindElement function is a high-level interface to enumerate elements from a compound file. 

For MMIO_FE_FINDFIRST and MMIO_FE_FINDNEXT, the pszE/ement parameter contains the name of an element in the specified 
compound file upon return. Only one MMIO_FE_FINDFIRST and MMIO_FE_FINDNEXT sequence is supported for a file at any one time. If 
an element is not found, MMIOERR_CF_ENTRY_NOT_FOUND is returned and the pszE/ement parameter is set to an empty string. 

For MMIO_FE_FINDELEMENT, the element name specified in pszE/ement is searched for. If the name is found, a zero return code is 
returned. If the element is not found, then MMIOERR_CF_ENTRY_NOT_FOUND is returned and the pszE/ement field is set to an empty 
string. 

MMIO_FE_FINDEND should be called after the search is complete. This flag indicates the compound file should be closed. 
MMIO_FE_FINDFIRST opens the compound file on the first invocation, and the file remains open until MMIO_FE_FINDEND is called. The 
MMIO_FE_FINDEND flag must be sent after completing the search in order to close the file. 


mmioFindElement - Related Functions 

• mmioRemoveElement 


mmioFindElement - Example Code 


The following code illustrates enumeration of compound-file entries. 

ULONG rc; 

CHAR szElement [CCHMAXPATH] ; 

rc=mmioFindElement (MMIO_FE_FINDFIRST, szElement, CCHMAXPATH, "TEST. Bnd", 0) ; 
while ( ! rc) { 

/* Save current szElement */ 

rc=mmioFindElement (MMIO_FE_FINDNEXT, szElement , CCHMAXPATH, "TEST. Bnd", 0) ; 

} 
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mmioFlush 


mmioFlush - Syntax 


This function writes the I/O buffer of a file to disk, if the I/O buffer was written into. It also empties the buffer if requested. 


#def ine INCL_MMIOOS2 
ftinclude <os2.h> 


HMMIO 

hmmio; 

/* 

Open file handle 

USHORT 

usFlags; 

/* 

Flags. */ 

USHORT 

rc; 

/* 

Return codes. */ 


rc = mmioFlush (hmmio, usFlags) ; 


mmioFlush Parameter - hmmio 


hmmio (FIMMIO) - input 

The open file handle returned by mmioOpen. 


mmioFlush Parameter - usFlags 


usFlags (USFIORT) - input 

Contains none or the following flag: 

MMIO_EMPTYBUF 

Empties the I/O buffer. The allocated buffer is not dropped, but the calling mmioGetlnfo will reveal that the pchNext 
field of the MMIOINFO structure will point to pchEndRead . 


mmioFlush Return Value - rc 


rc (USFIORT) - returns 

Return codes indicating success or type of failure: 


MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERR_CANNOTWRITE 

The buffer could not be written to the disk. The disk could be full. 
MMIOERR_WRITE_FAILED 

The buffer could not be written to the disk. This is a possible hardware problem. 

MMIOERR_NO_BUFFER_ALLOCATED 

A buffer was expected but was not present. 

MMIOERR_NO_FLUSH_NEEDED 

A mmioFlush function was requested, but the buffer was empty. 

MMIOERR_NO_FLUSH_FOR_MEM_FILE 

A mmioFlush was requested on a MEM file. 


mmioFlush - Parameters 


hmmio (FIMMIO) - input 

The open file handle returned by mmioOpen. 

usFlags (USFIORT) - input 

Contains none or the following flag: 

MMIO_EMPTYBUF 

Empties the I/O buffer. The allocated buffer is not dropped, but the calling mmioGetlnfo will reveal that the pchNext 
field of the MMIOINFO structure will point to pchEnc/Read . 

rc (USFIORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERR_CANNOTWRITE 

The buffer could not be written to the disk. The disk could be full. 

MMIOERR_WRITE_FAILED 

The buffer could not be written to the disk. This is a possible hardware problem. 

MMIOERR_NO_BUFFER_ALLOCATED 

A buffer was expected but was not present. 

MMIOERR_NO_FLUSH_NEEDED 

A mmioFlush function was requested, but the buffer was empty. 

MMIOERR_NO_FLUSH_FOR_MEM_FILE 

A mmioFlush was requested on a MEM file. 


mmioFlush - Remarks 


If the hmm/o parameter represents a file that was opened using mmioOpen, and hmm/o parameter is currently set up for buffered I/O, and 
the buffer has been written into (by mmioWrite, or by direct caller access to the buffer using mmioGetlnfo) since the last time the buffer was 
flushed to disk, mmioFlush writes the buffer to the disk. 

If the hmm/o parameter is a memory file or is unbuffered, this function returns the appropriate error message indicated. Note that 
mmioFlush might fail if there is insufficient disk space to write the buffer, even if the preceding mmioWrite functions succeeded. 


mmioFlush - Related Functions 


mmioSetBuffer 


mmioFlush - Example Code 


The following code illustrates how to write to disk. 

HMMIO hmmiol; 

USHORT usFlags = 0; 

USHORT rc; 


rc = mmioFlush ( hmmiol, usFlags) ; 
if (rc) 

/* error */ 
else 


mmioFlush - Topics 
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mmioFOURCC 


mmioFOURCC - Syntax 


This macro converts four characters to a four-character code (FOURCC). 


#def ine INCL_MMIOOS2 
#include <os2.h> 


CHAR 

chO; 

/* 

CHAR 

chi; 

/* 

CHAR 

ch2 ; 

/* 

CHAR 

ch3; 

/* 

FOURCC 

rc; 

/* 


First character. */ 
Second character. */ 
Third character. */ 
Fourth character. */ 
Four-character code. 


*/ 


rc = mmioFOURCC (chO , chi, ch2, ch3) ; 


mmioFOURCC Parameter - chO 


chO (CHAR) - input 

The first character of the FOURCC code to be converted. 


mmioFOURCC Parameter - chi 


chi (CHAR) - input 

The second character of the FOURCC code to be converted. 


mmioFOURCC Parameter - ch2 


ch2 (CHAR) - input 

The third character of the FOURCC code to be converted. 


mmioFOURCC Parameter - ch3 


ch3 (CHAR) - input 

The fourth character of the FOURCC code to be converted. 


mmioFOURCC Return Value - rc 


rc (FOURCC) - returns 

Returns the four-character code converted from the four characters as follows. Character chO is copied to the lowest address and 
ch3 is copied to the highest address. 


mmioFOURCC - Parameters 


chO (CHAR) - input 

The first character of the FOURCC code to be converted, 
chi (CHAR) - input 

The second character of the FOURCC code to be converted. 
ch2 (CHAR) - input 

The third character of the FOURCC code to be converted. 
ch3 (CHAR) - input 

The fourth character of the FOURCC code to be converted, 
rc (FOURCC) - returns 

Returns the four-character code converted from the four characters as follows. Character chO is copied to the lowest address and 
cfi3 is copied to the highest address. 


mmioFOURCC - Remarks 


This macro does not check to see if the four-character code follows any conventions regarding which characters to include in a FOURCC. 
The string is simply copied to a FOURCC and padded with blanks to the right, if required, or truncated to four characters, if required. 


mmioFOURCC - Related Functions 


mmioAscend 

mmioCreateChunk 

mmioDescend 

mmioStringToFOURCC 


mmioFOURCC - Example Code 


The following code illustrates how to convert four characters to a four-character code. 

#def ine FOURCC_WAVE = mmioFOURCC ( 'W', 'A', 'V, 'E' ); 


mmioFOURCC - Topics 
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mmioGetData 


mmioGetData - Syntax 


This function allows an application to access the MMIOINFO structure of the file referenced by timm/o and can be used to call an I/O 
procedure directly. 

Do not change any of the fields in the MMIOINFO structure as this information is stored within MMIO. 


#def ine INCL_MMIOOS2 
/(include <os2.h> 


HMMIO 

hmmio; 

/* 

Open file handle. */ 

PMMIOINFO 

pmmioinfo; 

/* 

Information receiver. */ 

USHORT 

usFlags; 

/* 

Reserved. */ 

USHORT 

rc; 

/* 

Return codes. */ 


rc = mmioGetData (hmmio, pmmioinfo, usFlags) ; 


mmioGetData Parameter - hmmio 


hmmio (FIMMIO) - input 

The open file handle returned by mmioOpen. 


mmioGetData Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) - in/out 

A caller-allocated MMIOINFO buffer that is to receive information about the open file. See the description of the mmioOpen function 
for information about how the fields are interpreted. 


mmioGetData Parameter - usFlags 


usFlags (USHORT) - input 

Reserved for future use and must be set to zero. 


mmioGetData Return Value - rc 


rc (USHORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERRJJNBUFFERED 

The specified file is not opened for buffered I/O. 

MMIOERR_READ_FAILED 

A read-advance operation failed. 

MMIOERR_SEEK_FAILED 

A seek operation prior to a write- or read-advance operation failed. 

MMIOERR_WRITE_FAILED 

A write-advance operation failed. 


mmioGetData - Parameters 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 

pmmioinfo (PMMIOINFO) - in/out 

A caller-allocated MMIOINFO buffer that is to receive information about the open file. See the description of the mmioOpen function 
for information about how the fields are interpreted. 

usFlags (USHORT) - input 

Reserved for future use and must be set to zero. 

rc (USHORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 


MMIOERR INVALID PARAMETER 


An invalid parameter was passed. 


MMIOERRJJNBUFFERED 

The specified file is not opened for buffered I/O. 

MMIOERR_READ_FAILED 

A read-advance operation failed. 

MMIOERR_SEEK_FAILED 

A seek operation prior to a write- or read-advance operation failed. 

MMIOERR_WRITE_FAILED 

A write-advance operation failed. 


mmioGetData - Remarks 


mmioGetData fills in all of the fields of the MMIOINFO structure, whereas mmioGetlnfo fills in only the buffered I/O fields. Because an 
application requires a complete copy of the MMIOINFO structure when calling an I/O procedure directly, mmioGetlnfo cannot be used. 


mmioGetData - Related Functions 


mmioGetlnfo 


mmioGetData - Example Code 


The following code illustrates how to access the MMIOINFO data structure. 

HMMIO hmmiol; 

MMIOINFO mmioinfo; 

USHORT usFlags = 0; 

USHORT rc; 


memset ( &mmioinfo, ' \0', sizeof (MMIOINFO) ); 

rc = mmioGetData ( hmmiol, &mmioinfo, usFlags) ; 
if (rc) 

/* error */ 
else 
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mmioGetFormatName 


mmioGetFormatName - Syntax 


This function provides the descriptive name of the format supported by the I/O procedure. 


#def ine INCL_MMIOOS2 
/(include <os2.h> 


PMMFORMATINFO 

pmmformatinfo; 

/* 

Pointer to MMFORMATINFO data structure 

PSZ 

pszFormatName; 

/* 

Pointer to format name. */ 

PLONG 

pIBytesRead; 

/* 

Pointer to a LONG. */ 

ULONG 

ulReserved; 

/* 

Reserved. */ 

ULONG 

ulFlags; 

/* 

Reserved. */ 

ULONG 

rc ; 

/* 

Return codes. */ 


rc = mmioGetFormatName (pmmformatinfo, pszFormatName, 
pIBytesRead, ulReserved, ulFlags) ; 


mmioGetFormatName Parameter - pmmformatinfo 


pmmformatinfo (PMMFORMATINFO) - input 

Pointer to an MMFORMATINFO structure that contains the fcc/OProc field (FOURCC code of the lOProc) and the /NameLength 
field, (the length in bytes of the format pointed to by the pszFormatName parameter). 


mmioGetFormatName Parameter - pszFormatName 


pszFormatName (PSZ) - output 

Pointer to a format name. This function fills in the format name associated with the specified lOProc, up to the length, in bytes, 
specified by the /NameLength field. Make sure the buffer is /NameLength + 1 in length to handle the string terminator character. 


mmioGetFormatName Parameter - pIBytesRead 


pIBytesRead (PLONG) - output 

Pointer to a LONG. The number of bytes read into pszFormatName is returned, representing the length of the format name. 


mmioGetFormatName Parameter - ulReserved 


ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioGetFormatName Parameter - ulFlags 


ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioGetFormatName Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following return. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 


mmioGetFormatName - Parameters 


pmmformatinfo (PMMFORMATINFO) - input 

Pointer to an MMFORMATINFO structure that contains the fcc/OProc field (FOURCC code of the lOProc) and the /NameLength 
field, (the length in bytes of the format pointed to by the pszFormatName parameter). 

pszFormatName (PSZ) - output 

Pointer to a format name. This function fills in the format name associated with the specified lOProc, up to the length, in bytes, 
specified by the /NameLength field. Make sure the buffer is /NameLength + 1 in length to handle the string terminator character. 

pIBytesRead (PLONG) - output 

Pointer to a LONG. The number of bytes read into pszFormatName is returned, representing the length of the format name. 

ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 


ulFlags (ULONG) - input 


Reserved for future use and must be set to zero. 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following return. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 


mmioGetFormatName - Remarks 


An application can use this function in conjunction with the mmioldentifyFile function to determine the size of the buffer needed to supply this 
call. 


mmioGetFormatName - Related Functions 


mmioGetFormats 

mmioldentifyFile 


mmioGetFormatName - Example Code 


The following code illustrates how to determine the format name associated with the lOProc. 

MMFORMATINFO mmFormat Inf o; 

PSZ pszFormatName; 

USHORT lBytesRead; 

ULONG ulReserved = OL; 

ULONG ulFlags = OL; 

ULONG rc; 


memset ( &mmFormatInfo, '\0', sizeof (MMFORMATINFO) ); 
mmFormatlnf o . INameLength = 40L; 
mmFormatlnf o . f ccIOProc = FOURCC_BND; 
mmFormatlnf o . ulStructLen=sizeof (MMFORMATINFO) ; 


rc = mmioGetFormatName ( 


if (rc) 

/* error */ 
else 


&mmf ormatinf o, 
pszFormatName, 
&lBytesRead, 
ulReserved, 
ulFlags) ; 


mmioGetFormatName - Topics 
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mmioGetFormats 


mmioGetFormats - Syntax 


This function provides a list of all I/O procedures available for use. 

#def ine INCL_MMIOOS2 
/(include <os2.h> 


PMMFORMATINFO 

pmmformatinfo; 

/* 

Pointer to MMFORMATINFO structure. */ 

LONG 

INumFormats; 

/* 

Number of formats. */ 

PVOID 

pFormatlnfoList ; 

/* 

Pointer to memory-allocated structure 

PLONG 

plFormatsRead; 

/* 

Number of formats read. */ 

ULONG 

ulReserved; 

/* 

Reserved. */ 

ULONG 

ulFlags; 

/* 

Reserved. */ 

ULONG 

rc; 

/* 

Return codes. */ 

rc = mmioGetFormats (pmmformatinfo, 

INumFormats , 


pFormatlnfoList, plFormatsRead, ulReserved, 
ulFlags) ; 


mmioGetFormats Parameter - pmmformatinfo 


pmmformatinfo (PMMFORMATINFO) - in/out 

A pointer to an MMFORMATINFO structure that might have optionally set the fcc/OProc field (FOURCC code) or u/Med/aType field 
(multimedia data type). These two fields provide the search criteria for matching an MMFORMATINFO structure. If both of these 
fields are NULL, then all I/O procedure MMFORMATINFO structures are returned, provided enough space is allocated for in the 
buffer pointed to by the pFormat/nfoL/st parameter. 


mmioGetFormats Parameter - INumFormats 


INumFormats (LONG) - input 

The maximum number of MMFORMATINFO structures that can be returned in the pFormat/nfoL/st parameter buffer. 


mmioGetFormats Parameter - pFormatlnfoList 


pFormatlnfoList (PVOID) - in/out 

Pointer to a buffer that will be filled with a list of matched MMFORMATINFO structures. The application needs to allocate enough 
memory to hold the requested number of structures. 


mmioGetFormats Parameter - pIFormatsRead 


pIFormatsRead (PLONG) - output 

Pointer to a LONG data type. Returns the number of formats that were returned in the pFormat/nfoL/st parameter buffer. 


mmioGetFormats Parameter - ulReserved 


ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioGetFormats Parameter - ulFlags 


ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioGetFormats Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following returns in this list. 


MMIOERR INVALID PARAMETER 


An invalid parameter was passed. 

MMIOERR_INTERNAL_SYSTEM 

An internal system error occurred. 


mmioGetFormats - Parameters 


pmmformatinfo (PMMFORMATINFO) - in/out 

A pointer to an MMFORMATINFO structure that might have optionally set the fcc/OProc field (FOURCC code) or u/Med/aType field 
(multimedia data type). These two fields provide the search criteria for matching an MMFORMATINFO structure. If both of these 
fields are NULL, then all I/O procedure MMFORMATINFO structures are returned, provided enough space is allocated for in the 
buffer pointed to by the pFormat/nfoL/st parameter. 

INumFormats (LONG) - input 

The maximum number of MMFORMATINFO structures that can be returned in the pFormat/nfoL/st parameter buffer. 

pFormatlnfoList (PVOID) - in/out 

Pointer to a buffer that will be filled with a list of matched MMFORMATINFO structures. The application needs to allocate enough 
memory to hold the requested number of structures. 

pIFormatsRead (PLONG) - output 

Pointer to a LONG data type. Returns the number of formats that were returned in the pFormat/nfoL/st parameter buffer. 

ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 

ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 

rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following returns in this list. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERR_INTERNAL_SYSTEM 

An internal system error occurred. 


mmioGetFormats - Remarks 


An application can use the mmioQueryFormatCount function to query the number of formats supported. It can then call mmioGetFormats 
with the correct size of pFormat/nfoL/st to obtain descriptive information about the file formats supported by currently installed I/O 
procedures. This listing will assist you in finding out which data types can be output to a device. You can also use mmioGetFormats to query 
the number of file formats supported. To allocate the buffer for the file formats supported, multiply the number of formats by the size of the 
MMFORMATINFO structure. (The MMFORMATINFO structures are all the same size.) 


mmioGetFormats - Related Functions 


mmioQueryFormatCount 

mmioGetFormatName 


mmioGetFormats - Example Code 


The following code illustrates how to obtain information about formats supported by currently installed I/O procedures. 

MMFORMAT INFO mmf ormatinf o; 

LONG INumFormats; 

PCHAR pFormatlnf oList ; 

LONG lFormatsRead; 

PCHAR pFormatlnf oList ; 

ULONG ulReserved = OL; 

ULONG ulFlags = OL; 

ULONG rc; 


memset ( &mmf ormatinf o, ' \0', sizeof (MMFORMAT INFO) ); 
mmf ormatinf o.ulMediaType |= MMIO_MEDIATYPE_AUDIO; 
INumFormats = 3; 

rc = mmioGetFormats ( &mmf ormatinf o, 

INumFormats , 
pFormatlnf oList , 

& lFormatsRead, 
ulReserved, 
ulFlags) ; 

if (rc) 

/* error */ 
else 


mmioGetFormats - Topics 
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mmioGetHeader 


mmioGetFleader - Syntax 


This function requests a media-specific header for an open file. The specific header depends on the media type of the file and current track 


setting, in the case of multiple tracks. This header can be a raw header or a translated header. 

This function does not change the current file position. It is highly recommended that mmioGetHeader be called before performing 
mmioRead because this information is normally required to understand the data that is read. 


#def ine INCL_MMIOOS2 
#include <os2.h> 


HMMIO 

hmmio; 

/* 

PVOID 

pHeader; 

/* 

LONG 

lHeaderLength; 

/* 

PLONG 

plBytesRead; 

/* 

ULONG 

ulReserved; 

/* 

ULONG 

ulFlags; 

/* 

ULONG 

rc ; 

/* 


Open file handle. */ 

Pointer to header structure. */ 
Header structure size. */ 

# of bytes read. */ 

Reserved. */ 

Reserved. */ 

Return codes. */ 


rc = mmioGetHeader (hmmio, pHeader, lHeaderLength, 
plBytesRead, ulReserved, ulFlags) ; 


mmioGetHeader Parameter - hmmio 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


mmioGetHeader Parameter - pHeader 


pHeader (PVOID) - input 

Pointer to a header structure. This structure is filled in by the lOProc. If the MMIO_TRANSLATEHEADER flag was set in the 
u/Trans/ate field of MMIOINFO on the mmioOpen, then the header returned is one associated with the standard presentation format 
for that particular media type. Each media type has a different header. 

The I/O procedure is expected to transpose native header information, as read from the file, into the standard presentation format 
header before passing the data to the caller. The currently defined values for each media type ( u/Med/aType ) and their respective 
media structures are as follows: 

Note: If MMIO_NOTRANSLATE was specified on the open (default case) then the file format native header is returned. 
MMIO_MEDIATYPE_IMAGE 

The data represents a still image. Images use MMIMAGEHEADER as the media structure. 
MMIO_MEDIATYPE_AUDIO 

The data represents digital audio. Digital-audio data streams use MMAUDIOHEADER as the media structure. 
MMIO_MEDIATYPE_MIDI 

The data represents MIDI streams. MIDI data streams use MMMIDIHEADER as the media structure. 
MMIO_MEDIATYPE_DIGITALVIDEO 

The data represents digital video. Digital video data streams use MMVIDEOHEADER as the media structure. 
MMIO_MEDIATYPE_MOVIE 

The data represents a movie. Movie data uses MMMOVIEHEADER as the media structure. 


mmioGetHeader Parameter - lHeaderLength 


IHeaderLength (LONG) - input 

The size, in bytes, of the header structure. 


mmioGetHeader Parameter - pIBytesRead 


pIBytesRead (PLONG) - in/out 

Returns the number of bytes read to the header structure. 


mmioGetHeader Parameter - ulReserved 


ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioGetHeader Parameter - ulFlags 


ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioGetHeader Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The specified file is not a media-file format type. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERRINTERNALSYSTEM 

An internal system error occurred. 

MMIOERR_SEEK_FAILED 

A seek operation prior to a write- or read-advance operation failed. 


mmioGetHeader - Parameters 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 

pHeader (PVOID) - input 

Pointer to a header structure. This structure is filled in by the lOProc. If the MMIO_TRANSLATEHEADER flag was set in the 
u/Trans/ate field of MMIOINFO on the mmioOpen, then the header returned is one associated with the standard presentation format 
for that particular media type. Each media type has a different header. 

The I/O procedure is expected to transpose native header information, as read from the file, into the standard presentation format 
header before passing the data to the caller. The currently defined values for each media type ( u/Med/aType ) and their respective 
media structures are as follows: 

Note: If MMIO_NOTRANSLATE was specified on the open (default case) then the file format native header is returned. 

M M IO_M E D I ATYP E_l M AG E 

The data represents a still image. Images use MMIMAGEHEADER as the media structure. 
MMIO_MEDIATYPE_AUDIO 

The data represents digital audio. Digital-audio data streams use MMAUDIOHEADER as the media structure. 
MMIO_MEDIATYPE_MIDI 

The data represents MIDI streams. MIDI data streams use MMMIDIHEADER as the media structure. 
MMIO_MEDIATYPE_DIGITALVIDEO 

The data represents digital video. Digital video data streams use MMVIDEOHEADER as the media structure. 
MMIO_MEDIATYPE_MOVIE 

The data represents a movie. Movie data uses MMMOVIEHEADER as the media structure. 

IHeaderLength (LONG) - input 

The size, in bytes, of the header structure. 

pIBytesRead (PLONG) - in/out 

Returns the number of bytes read to the header structure. 

ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 

ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 

rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The specified file is not a media-file format type. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERRINTERNALSYSTEM 

An internal system error occurred. 

MMIOERR_SEEK_FAILED 

A seek operation prior to a write- or read-advance operation failed. 


mmioGetHeader - Remarks 


The p/BytesRead parameter value might differ from the actual number of bytes read from the file in the case of translations. 

Compound files are not supported by the mmioGetHeader function. Only non-compound files and compound-file elements are supported. 

This function can be used in conjunction with the mmioSet function to query specific track headers from a multiple track movie file. 

If the length passed in was not large enough to hold the header, MMIOERR_INVALID_BUFFER_LENGTH is set in u/ErrorRet. If the header 
is in error, MMIOERR INVALID STRUCTURE is set in u/ErrorRet. 


mmioGetHeader - Related Functions 


mmioSetFleader 

mmioldentifyFile 


mmioGetHeader - Example Code 


The following code illustrates how to return the header of a file. 

HMMIO hmmiol; 

PCHAR pHeader; 

USHORT lHeaderLength; 

USHORT LONG lBytesRead; 

ULONG ulReserved = OL; 

ULONG ulFlags = OL; 

ULONG rc; 


rc = mmioGetHeader ( 


if (rc) 

/* error */ 
else 


hmmiol , 

pHeader, 

lHeaderLength, 

&lBytesRead, 

ulReserved, 

ulFlags) ; 
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mmioGetlnfo 


mmioGetlnfo - Syntax 


This function gets information about a file that was opened with mmioOpen. It also allows the caller to access the I/O buffer directly. 


#def ine INCL_MMIOOS2 
#include <os2.h> 


HMMIO 

hmmio; 

/* 

PMMIOINFO 

pmmioinfo; 

/* 

USHORT 

usFlags; 

/* 

USHORT 

rc; 

/* 


Open file handle. */ 
Information receiver. */ 
Reserved. */ 

Return codes. */ 


rc = mmioGetlnfo (hmmio, pmmioinfo, usFlags) ; 


mmioGetlnfo Parameter - hmmio 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


mmioGetlnfo Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) - in/out 

A caller-allocated MMIOINFO buffer that is to receive information about the open file. See the description of the mmioOpen function 
for information about how the fields are interpreted. 


mmioGetlnfo Parameter - usFlags 


usFlags (USHORT) - input 

Reserved for future use and must be set to zero. 


mmioGetlnfo Return Value - rc 


rc (USHORT) - returns 


Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERR INVALID HANDLE 

The handle passed was not valid. 

MMIOERR_INVALID_PARAMETER 

An invalid parameter was passed. 

MMIOERRJJNBUFFERED 

The specified file is not opened for buffered I/O. 

MMIOERR_READ_FAILED 

A read-advance operation failed. 

MMIOERR_SEEK_FAILED 

A seek operation prior to a write- or read-advance operation failed. 

MMIOERR_WRITE_FAILED 

A write-advance operation failed. 


mmioGetlnfo - Parameters 


hmmio (FIMMIO) - input 

The open file handle returned by mmioOpen. 

pmmioinfo (PMMIOINFO) - in/out 

A caller-allocated MMIOINFO buffer that is to receive information about the open file. See the description of the mmioOpen function 
for information about how the fields are interpreted. 

usFlags (USPIORT) - input 

Reserved for future use and must be set to zero. 

rc (USPIORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERR INVALID PARAMETER 

An invalid parameter was passed. 

MMIOERRJJNBUFFERED 

The specified file is not opened for buffered I/O. 

MMIOERR_READ_FAILED 

A read-advance operation failed. 

MMIOERR_SEEK_FAILED 

A seek operation prior to a write- or read-advance operation failed. 

MMIOERR_WRITE_FAILED 

A write-advance operation failed. 


mmioGetlnfo - Remarks 


An application can access the I/O buffer directly, as follows: 


Call mmioGetlnfo. The pch/Vext field of the MMIOINFO structure is a pointer to the next byte that can be read from or written to. 

To read directly from the buffer, the application reads from the location pointed to by pch/Vext up to (but not including) the 
location pointed to by the pchEndf/ead pointer. 

To write directly to the buffer, the application writes to the location pointed to by pch/Vext up to (but not including) the location 
pointed to by the pchEndl/Vr/te pointer. 

Once pch/Vext is modified, do not call any MMIO functions (except for mmioAdvance) until mmioSetlnfo is called. In particular, 
do not call mmioRead and mmioWrite. Once mmioSetlnfo is called, the caller must stop accessing the I/O buffer directly, and 
revert to using mmioRead and mmioWrite to read and write the file. 

To read beyond pchEndF/ead or write beyond pchEndWr/te , call mmioAdvance to read and write the contents of the next full 
buffer. mmioAdvance will adjust various fields in your MMIOINFO block, including pch/Vext , pchEndRead , and pchEndWr/te . 

Before calling mmioAdvance or mmioSetlnfo, make sure you set the MMIO_DIRTY flag of the u/F/ags field of the MMIOINFO 
structure passed in the pmm/o/nfo parameter if you have written to the buffer. Otherwise, the buffer contents will not get written 
to the disk. 

The caller must not move pch/Vext backward. No fields other than pch/Vext and the MMIO_DIRTY flag of u/F/ags are to be 
modified. 


mmioGetlnfo - Related Functions 


mmioAdvance 

mmioGetData 

mmioSetlnfo 


mmioGetlnfo - Example Code 


The following code illustrates how to get information about a file. 

HMMIO hmmiol; 

MMIOINFO mmioinfo; 

USHORT usFlags = 0; 

USHORT rc; 


memset ( &mmioinfo, ' \0', sizeof (MMIOINFO) ); 

rc = mmioGetlnfo ( hmmiol, &mmioinfo, usFlags) ; 
if (rc) 

/* error */ 
else 
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mmioGetLastError 


mmioGetLastError - Syntax 


This function returns the last error condition stored in the u/Errorftet field of the MMIOINFO structure that might contain additional 
information for the analysis of the last error routine. 


#def ine INCL_MMIOOS2 
#include <os2.h> 

HMMIO hmmio; /* Open file handle. */ 

ULONG rc; /* Return code. */ 

rc = mmioGetLastError (hmmio) ; 


mmioGetLastError Parameter - hmmio 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


mmioGetLastError Return Value - rc 


rc (ULONG) - returns 

Return code indicating success or type of failure: 


MMIOERRINVALIDHANDLE 

An invalid handle was passed. 


mmioGetLastError - Parameters 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 

rc (ULONG) - returns 

Return code indicating success or type of failure: 

MMIOERRINVALIDHANDLE 

An invalid handle was passed. 


mmioGetLastError - Remarks 


The user can call mmioGetLastError for those functions that return only MMIO_ERROR or MMIO_CF_FAILURE, and obtain additional 
information about the failing condition from the u/ErrorRet field of the MMIOINFO structure. If u/ErrorRet does not contain an MMIO error 
code, it contains an OS/2 error code or 0. 


mmioGetLastError - Example Code 


The following code illustrates how to return the last error condition. 

HMMIO hmmio 1; 

ULONG rc; 


rc = mmioGetLastError ( hmmiol ) ; 
if (rc) 

/* error */ 
else 


mmioGetLastError - Topics 


Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Example Code 

Glossary 


mmioldentifyFile 


mmioldentifyFile - Syntax 


This function will determine (if possible) the format of a file by either using the file name or querying currently installed I/O procedures to see 
which I/O procedure can understand and process the specified file. 


#def ine INCL_MMIOOS2 
/(include <os2.h> 


PSZ 

pszFileName; 

/* 

Filename. */ 

PMMIOINFO 

pmmioinfo; 

/* 

Pointer to MMIOINFO. */ 

PMMFORMATINFO 

pmmformatinfo; 

/* 

Pointer to MMFORMATINFO 

PFOURCC 

pfccStorageSystem; 

/* 

FOURCC pointer. */ 

ULONG 

ulReserved; 

/* 

Reserved. */ 

ULONG 

ulFlags; 

/* 

Flags. */ 

ULONG 

rc ; 

/* 

Return codes. */ 


rc = mmioldentif yFile (pszFileName, pmmioinfo, 

pmmf ormatinf o, pf ccStorageSystem, ulReserved, 
ulFlags) ; 


mmioldentifyFile Parameter - pszFileName 


pszFileName (PSZ) - input 

The name of the file to identify. 


mmioldentifyFile Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) - input 

Pointer to an MMIOINFO structure. This parameter is needed when a RIFF compound-file element is not completely valid. Normally 
this is NULL. 


mmioldentifyFile Parameter - pmmformatinfo 


pmmformatinfo (PMMFORMATINFO) - in/out 

Pointer to an MMFORMATINFO structure that, upon return from the function, contains information about the I/O procedure that 
handles this format. This includes the media type, such as image, audio, and compound, and the I/O procedure FOURCC code value 
that can then be used to open the file for further processing. This is returned only upon successful completion. 


mmioldentifyFile Parameter - pfccStorageSystem 


pfccStorageSystem (PFOURCC) - output 

A pointer that, upon return from the function, contains the FOURCC code of the storage system. 


mmioldentifyFile Parameter - ulReserved 


ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioldentifyFile Parameter - ulFlags 


ulFlags (ULONG) - input 

The following flags are defined: 

MMIO_FORCE_IDE NTI FY_SS 

Forces the identification of a storage system by ignoring the file name and actually checking the MMIO Manager's 
I/O procedure list. 

MMIO_FORCE_IDENTIFY_FF 

Forces the identification of a file format by ignoring the file name and actually checking the MMIO Manager's I/O 
procedure list. 


mmioldentifyFile Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure. For information about DOS File errors, use the mmioGetLastError function. 
MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following returns in this list. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERR_INTERNAL_SYSTEM 

An internal system error occurred. 


mmioldentifyFile - Parameters 


pszFileName (PSZ) - input 

The name of the file to identify. 

pmmioinfo (PMMIOINFO) - input 

Pointer to an MMIOINFO structure. This parameter is needed when a RIFF compound-file element is not completely valid. Normally 
this is NULL. 

pmmformatinfo (PMMFORMATINFO) - in/out 


Pointer to an MMFORMATINFO structure that, upon return from the function, contains information about the I/O procedure that 
handles this format. This includes the media type, such as image, audio, and compound, and the I/O procedure FOURCC code value 
that can then be used to open the file for further processing. This is returned only upon successful completion. 

pfccStorageSystem (PFOURCC) - output 

A pointer that, upon return from the function, contains the FOURCC code of the storage system. 

ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 

ulFlags (ULONG) - input 

The following flags are defined: 

MMIO_FORCE_IDE NTI FY_SS 

Forces the identification of a storage system by ignoring the file name and actually checking the MMIO Manager's 
I/O procedure list. 

MMIO_FORCE_IDENTIFY_FF 

Forces the identification of a file format by ignoring the file name and actually checking the MMIO Manager's I/O 
procedure list. 


rc (ULONG) - returns 

Return codes indicating success or type of failure. For information about DOS File errors, use the mmioGetLastError function. 
MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following returns in this list. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERR_INTERNAL_SYSTEM 

An internal system error occurred. 


mmioldentifyFile - Remarks 


The order of I/O procedures to be searched is controlled by the MMPMMMIO.INI file; the order in which they are installed is controlled by 
mmiolnstalllOProc. The last installed procedure is first in the list. You can control the order of search based on the formats you normally use. 

The default match will be the DOS I/O procedure. 


mmioldentifyFile - Related Functions 


mmioOpen 

mmioldentifyStorageSystem 

mmioDetermineSSIOProc 


mmioldentifyFile - Example Code 


The following code illustrates how to determine the file processing capability of the lOProcs. 


MMIOINFO mmioinfo; 


MMFORMATINFO mmFormat Inf o; 
FOURCC fccType; 

ULONG ulReserved = OL; 
ULONG ulFlags = OL; 

ULONG rc; 


memset ( &mmioinfo, ' \0', sizeof (MMIOINFO) ); 
memset ( &mmFormatInfo, '\0', sizeof (MMFORMATINFO) ); 

rc = mmioIdentifyFile ( "myf ile . bnd+element . f oo" , 

&mmioinf o, 

&mmFormat Inf o, 

&f ccType, 
ulReserved, 
ulFlags) ; 

if (rc) 

/* error */ 
else 


mmioIdentifyFile - Topics 
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mmioldentifyStorageSystem 


mmioldentifyStorageSystem - Syntax 


This function determines the storage system that contains the media data object. 


#def ine INCL_MMIOOS2 
#include <os2.h> 


PSZ 

pszFileName ; 

/* 

File name. */ 

PMMIOINFO 

pmmioinfo; 

/* 

Pointer to MMIOINFO. */ 

PFOURCC 

pf ccStorageSystem; 

/* 

Storage system pointer. 

ULONG 

rc; 

/* 

Return codes. */ 


rc = mmioldentifyStorageSystem (pszFileName, 
pmmioinfo, pf ccStorageSystem) ; 


mmioldentifyStorageSystem Parameter - pszFileName 


pszFileName (PSZ) - input 

The file name to be identified. 


mmioldentifyStorageSystem Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) - input 

A pointer to the MMIOINFO buffer that might contain additional data. Normally this is NULL, but is needed for compound-file elements 
when they are not fully qualified. 


mmioldentifyStorageSystem Parameter - pfccStorageSystem 


pfccStorageSystem (PFOURCC) - output 

Pointer to the FOURCC code of the storage system that gets returned upon successful completion. 


mmioldentifyStorageSystem Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure. For more information about DOS File errors, use the mmioGetLastError function. 
MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The specified file is not a storage-system type. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERR_INTERNAL_SYSTEM 

An internal system error occurred. 


mmioldentifyStorageSystem - Parameters 


pszFileName (PSZ) - input 

The file name to be identified. 


pmmioinfo (PMMIOINFO) - input 


A pointer to the MMIOINFO buffer that might contain additional data. Normally this is NULL, but is needed for compound-file elements 
when they are not fully qualified. 

pfccStorageSystem (PFOURCC) - output 

Pointer to the FOURCC code of the storage system that gets returned upon successful completion, 
rc (ULONG) - returns 

Return codes indicating success or type of failure. For more information about DOS File errors, use the mmioGetLastError function. 
MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The specified file is not a storage-system type. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERRINTERNALSYSTEM 

An internal system error occurred. 


mmioldentifyStorageSystem - Remarks 


mmioldentifyStorageSystem processes the MMIO internal I/O procedure list to determine if the file name specified is of type 
MMIO_IOPROC_STORAGESYSTEM. If it is, an MMIOMJDENTIFYFILE message is sent to the I/O procedure to see if it can identify the 
data object. The pfccStorageSystem parameter contains the FOURCC code of the I/O procedure that successfully identified the data object. 


mmioldentifyStorageSystem - Related Functions 


mmioDetermineSSIOProc 

mmioldentifyFile 


mmioldentifyStorageSystem - Example Code 


The following code illustrates how to determine the storage system. 

PSZ pszFileName; 

MMIOINFO mmioinfo; 

FOURCC f ccStorageSystem; 

ULONG rc; 


memset ( &mmioinfo, ' \0', sizeof (MMIOINFO) ); 
mmioinfo . fccIOProc = FOURCC_BND; 

strcpy ( pszFileName, "myf ile . bnd+element . f oo" ); 

rc = mmioldentifyStorageSystem ( pszFileName, 

&mmioinf o, 

&f ccStorageSystem) ; 

if (rc) 

/* error */ 
else 
{ 

if ( ! f ccStorageSystem) 

{ 


return (MMIO_ERROR) ; 


} 

else 

{ 

mmioinf o . f ccChildlOProc = f ccStorageSystem; 
} 

} 


mmioldentifyStorageSystem - Topics 
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mmiolniFileCODEC 


mmiolniFileCODEC - Syntax 


This function modifies the initialization file (MMPMMMIO.INI) for MMIO Manager services. It adds, replaces, removes, or finds a CODEC 
entry in the MMPMMMIO.INI file. 


#def ine INCL_MMIOOS2 
#def ine INCL_MMIO_CODEC 
#include <os2.h> 


PCODECINIFILEINFO 

ULONG 

ULONG 


pCODECIniFilelnf o; 

ulFlags; 

rc; 


/* Pointer. */ 

/* Flags. */ 

/* Return codes. */ 


rc = mmiolniFileCODEC (pCODECIniFilelnf o, ulFlags) ; 


mmiolniFileCODEC Parameter - pCODECIniFilelnfo 


pCODECIniFilelnfo (PCODECINIFILEINFO) - in/out 

A pointer to the CODECINIFILEINFO structure that contains the file format FOURCC, compression type, compression subtype, 
CODEC DLL name, entry procedure name, and other CODEC Procedure information. 


mmiolniFileCODEC Parameter - ulFlags 


ulFlags (ULONG) - input 

Specifies options for the operation. Contains one or more of the following flags: 

MMIOJNSTALLPROC 

Adds a CODEC Proc to the end of the MMPMMMIO.INI file. If an existing entry in the table matches the new 
entry, the new entry replaces the existing entry. An entry match is determined by specifying 0 or more of the 
match flags. If none are specified, the default is to match on the FOURCC. 

MMIO_REMOVEPROC 

Deletes a matching entry from the MMPMMMIO.INI file. An entry match is determined by specifying 0 or more 
of the match flags. If none are specified, the default is to match on the FOURCC. 

MMIO_FINDPROC 

Finds a matching entry from the MMPMMMIO.INI file. This fills in the remainder of the CODECINIFILEINFO. 
An entry match is determined by specifying 0 or more of the match flags. If none are specified, the default is to 
match on the FOURCC. 

Note: If MMIO_MATCHFIRST is set, then MMIO_FINDPROC does not default to the FOURCC. 

MMIO_MATCHFIRST 

Finds the first entry in the MMPMMMIO.INI file if no match flags are specified. Otherwise, it finds the first entry 
that matches the contents of the fields specified by the match flags. In either case, the CODECINIFILEINFO 
structure is returned in the pCODEC/r>/F//e/nfo parameter. 

MMIO_MATCHNEXT 

If no match flags are specified, finds the next CODEC entry in the MMPMMMIO.INI file following the entry 
passed in pCODEC/n/F//e/nfo . If match flags are specified, finds the next entry that matches the search 
criteria specified by the flags. In either case, the pCODEC/niFi/e/nfo structure is returned. 

MMIO_MATCHCOMPRESSTYPE 

Uses compression type ( u/CompressType field of CODECINIFILEINFO) as a search criteria. 
MMIO_MATCHCOMPRESSSUBTYPE 

Uses compression subtype ( u/CompressSubType field of CODECINIFILEINFO) as a search criteria. 


MMIO_MATCHHWID 

Uses hardware ID ( szHlV/D field of CODECINIFILEINFO) as a search criteria. 

MMIO_MATCHCAPSFLAGS 

Uses capability flags ( u/CapsF/ags of CODECINIFILEINFO) as a search criteria. Note that this search is not 
based on the exact match. If the target entry contains the flags, the match is satisfied. 

MM IO_MATCH FOURCC 

Uses the FOURCC code (fee field of CODECINIFILEINFO) as a search criteria. 

MMIO_MATCHDLL 

Uses the DLL Name ( szDLL/Vame field of CODECINIFILEINFO) as a search criteria. 
MMIO_MATCHPROCEDURENAME 

Uses the case-sensitive Procedure Name (szProcName field of CODECINIFILEINFO) as a search criteria. 


MMIO_FULLPATH 

Uses the drive or path given with the DLL name (szDLL/Vame field of CODECINIFILEINFO), otherwise use 
only the base file name. This allows DLLs with the same base name to be loaded from different directories. 


mmiolniFileCODEC Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following returns in this list. 

MMIO_INVALID_PARAMETER 

An invalid parameter was passed. 

MMIOERRINTERNALSYSTEM 

An internal system error was found. 

MMIOERR_NO_CORE 

Unable to allocate enough memory for the MMPMMMIO.INI data. 

MMIOERRINIOPEN 

Unable to open the MMPMMMIO.INI file. 

MMIOERR_INVALID_DLLNAME 

Unable to validate the DLL name. 

MMIOERR_INVALID_PROCEDURENAME 

Unable to validate the CODEC procedure name. 

MMIOERR_MATCH_NOT_FOUND 

Unable to FIND the FOURCC, compression, DLL, or procedure name in MMPMMMIO.INI. 

MMIOERR_CODEC_NOT_SUPPORTED 

Although the file format is supported, the particular CODEC is not. 


mmiolniFileCODEC - Parameters 


pCODECIniFilelnfo (PCODECINIFILEINFO) - in/out 

A pointer to the CODECINIFILEINFO structure that contains the file format FOURCC, compression type, compression subtype, 
CODEC DLL name, entry procedure name, and other CODEC Procedure information. 

ulFlags (ULONG) - input 

Specifies options for the operation. Contains one or more of the following flags: 

MMIOJNSTALLPROC 

Adds a CODEC Proc to the end of the MMPMMMIO.INI file. If an existing entry in the table matches the new 
entry, the new entry replaces the existing entry. An entry match is determined by specifying 0 or more of the 
match flags. If none are specified, the default is to match on the FOURCC. 

MMIO_REMOVEPROC 

Deletes a matching entry from the MMPMMMIO.INI file. An entry match is determined by specifying 0 or more 
of the match flags. If none are specified, the default is to match on the FOURCC. 

MMIO_FINDPROC 

Finds a matching entry from the MMPMMMIO.INI file. This fills in the remainder of the CODECINIFILEINFO. 
An entry match is determined by specifying 0 or more of the match flags. If none are specified, the default is to 
match on the FOURCC. 

Note: If MMIO_MATCHFIRST is set, then MMIO_FINDPROC does not default to the FOURCC. 

MMIO_MATCHFIRST 

Finds the first entry in the MMPMMMIO.INI file if no match flags are specified. Otherwise, it finds the first entry 
that matches the contents of the fields specified by the match flags. In either case, the CODECINIFILEINFO 
structure is returned in the pCODEC/n/F//e/nfo parameter. 

MMIO_MATCHNEXT 

If no match flags are specified, finds the next CODEC entry in the MMPMMMIO.INI file following the entry 


passed in pCODEC/nZFZZe/nfo . If match flags are specified, finds the next entry that matches the search 
criteria specified by the flags. In either case, the pCODEC/nZFZ/e/nfo structure is returned. 

MMIO_MATCHCOMPRESSTYPE 

Uses compression type ( u/CompressType field of CODECINIFILEINFO) as a search criteria. 
MMIO_MATCHCOMPRESSSUBTYPE 

Uses compression subtype ( u/CompressSubType field of CODECINIFILEINFO) as a search criteria. 

MMIO_MATCHHWID 

Uses hardware ID (szZ/IW/D field of CODECINIFILEINFO) as a search criteria. 

MMIO_MATCHCAPSFLAGS 

Uses capability flags ( u/CapsFZags of CODECINIFILEINFO) as a search criteria. Note that this search is not 
based on the exact match. If the target entry contains the flags, the match is satisfied. 

MMIO_MATCHFOURCC 

Uses the FOURCC code ( fee field of CODECINIFILEINFO) as a search criteria. 

MMIO_MATCHDLL 

Uses the DLL Name ( szDLL/SZame field of CODECINIFILEINFO) as a search criteria. 
MMIO_MATCHPROCEDURENAME 

Uses the case-sensitive Procedure Name ( szProcZVame field of CODECINIFILEINFO) as a search criteria. 

MMIO_FULLPATH 

Uses the drive or path given with the DLL name ( szDLL/Vame field of CODECINIFILEINFO), otherwise use 
only the base file name. This allows DLLs with the same base name to be loaded from different directories. 

rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following returns in this list. 

MMIO_INVALID_PARAMETER 

An invalid parameter was passed. 

MMIOERR_INTERNAL_SYSTEM 

An internal system error was found. 

MMIOERR_NO_CORE 

Unable to allocate enough memory for the MMPMMMIO.INI data. 

MMIOERRINIOPEN 

Unable to open the MMPMMMIO.INI file. 

MMIOERRINVALIDDLLNAME 

Unable to validate the DLL name. 

MMIOERRINVALIDPROCEDURENAME 

Unable to validate the CODEC procedure name. 

MMIOERR_MATCH_NOT_FOUND 

Unable to FIND the FOURCC, compression, DLL, or procedure name in MMPMMMIO.INI. 

MMIOERR_CODEC_NOT_SUPPORTED 

Although the file format is supported, the particular CODEC is not. 


mmiolniFileCODEC - Remarks 


The MMPMMMIO.INI file is in the directory specified in the MMBASE environment variable. 


The DLL name ( szDLL/Vame ) specified in the CODECINIFILEINFO structure must follow the same naming conventions as the 
DosLoadModule function. If the DLL or procedure name is invalid, an error is returned. 

In a deletion, the entry is removed and the entire file is rewritten, to prevent it from growing with deleted entries. This is due to how OS/2 
functions delete entries from INI files. Deleted entries are not reused. 


mmiolniFileCODEC - Example Code 


The following code illustrates how to add, replace, remove, or find a CODEC entry in the MMPMMMIO.INI file. 

CODECINIFILEINFO codecIniFilelnf o; 

ULONG ulFlags = OL; 

ULONG rc; 


memset ( &codecIniFileInf o, ' \0', sizeof (CODECINIFILEINFO) ); 
codecIniFilelnf o . ulStructLen = sizeof (CODECINIFILEINFO); 
codecIniFilelnf o. fee = FOURCC_MYPROC; 

codecIniFilelnf o.ulCompressType = COMPRESSTYPE_MYPROC; 

codecIniFilelnf o.ulCompressSubType = COMPRESSSUBTYPE_MYPROC; 

codecIniFilelnf o.ulMediaType = MEDIATYPE_MYPROC ; 

codecIniFilelnf o . ulCapsFlags = CODEC_DECOMPRESS; 

codecIniFilelnf o . szHWID = HWID_MYPROC; 

codecIniFilelnf o . ulMaxScrBuf len = MAXBUFLEN_MYPROC ; 

codecIniFilelnf o . ulSyncMethod = SYNCMETHOD_MYPROC ; 

codecIniFilelnf o.ulXalignment = XALIGNMENT_MYPROC ; 

codecIniFilelnf o.ulYalignment = YALIGNMENT_MYPROC ; 

strnepy ( codecIniFilelnf o . szDLLName, "MYPROC" , DLLNAME_S I ZE ); 

strnepy ( codecIniFilelnf o . szProcName, "MyCODECProc" , PROCNAME_SIZE ); 

ulFlags = MMIO_INSTALLPROC 

MMIO_MATCHCOMPRESSTYPE | MMIO_MATCHCOMPRESSSUBTYPE ; 
MMIO_MATCHCAPSFLAGS | MMIO_MATCHHWID 
rc = mmiolniFileCODEC ( &codecIniFileInf o, 

ulFlags) ; 

if (rc) 

/* error */ 
else 
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mmiolniFileHandler 


mmiolniFileHandler - Syntax 


This function adds, replaces, removes, or finds an I/O procedure in the initialization file (MMPMMMIO.INI) for MMIO services. 


#def ine INCL_MMIOOS2 
#include <os2.h> 


PMMINIFILEINFO 

pmminifileinfo; 

/* 

Pointer to MMINIFILEINFO. */ 

ULONG 

ulFlags; 

/* 

Operation options. */ 

ULONG 

rc; 

/* 

Return codes. */ 


rc = mmiolniFileHandler (pmminifileinfo, ulFlags) ; 


mmiolniFileHandler Parameter - pmminifileinfo 


pmminifileinfo (PMMINIFILEINFO) - input 

A pointer to the MMINIFILEINFO structure that contains the FOURCC code, DLL name, and the name of the I/O procedure. 


mmiolniFileHandler Parameter - ulFlags 


ulFlags (ULONG) - input 

Specifies options for the operation. Contains one of the following flags: 

MMIOJNSTALLPFiOC 

Adds an I/O procedure to the end of the MMPMMMIO.INI file. If an existing entry in the table matches the new 
entry, the new entry replaces the existing entry. An entry match is determined by specifying 0 or more of the 
match flags. If none are specified, the default is to match on the FOURCC code. 

MMIO_REMOVEPROC 

Deletes a matching entry from the MMPMMMIO.INI file. An entry match is determined by specifying 0 or more 
of the match flags. If none are specified, the default is to match on the FOURCC code. 

MMIO_FINDPROC 

Finds a matching entry from the MMPMMMIO.INI file. This fills in the remainder of the MMINIFILEINFO 
structure passed in the pmminifi/e/nfo parameter. An entry match is determined by specifying 0 or more of the 
match flags. If none are specified, the default is to match on the FOURCC. 

Note: If MMIO_FINDFIRST is set, then MMIO_FINDPROC does not default to the FOURCC. 

MMIO_MATCHFIRST 

Finds the first entry in the MMPMMMIO.INI file if no match flags are specified. Otherwise, it finds the first entry 
that matches the contents of the fields specified by the match flags. In either case, the MMINIFILEINFO 
structure is returned. 

MMIO_MATCHNEXT 

If no match flags are specified, this finds the next entry in the MMPMMMIO.INI file following the entry 
(MMINIFILEINFO structure) passed in the pmm/nifi/e/nfo parameter. If match flags are specified, this finds the 
next entry that matches the search criteria specified by the flags. In either case, the MMINIFILEINFO structure 
is returned. 

MM IO_MATCH FOURCC 

Use the FOURCC code ( fcc/OProc field of the MMINIFILEINFO structure) as a search criteria. 


MMIO_MATCHDLL 


Use the DLL Name ( szDLL/Vame field of the MMINIFILEINFO structure) as a search criteria. 
MMIO_MATCHPROCEDURENAME 

Use the case-sensitive procedure name ( szProc/Vame field of the MMINIFILEINFO structure) as a search 
criteria. 


MMIO_FULLPATH 

Use the drive or path given with the DLL name [szDLL/Vame field of the MMINIFILEINFO structure), 
otherwise use only the base file name. This allows DLLs with the same base name to be loaded from different 
directories. 

MMIO_EXTENDED_STRUCT 

This flag must be set for release 1.1 and later releases. It indicates the expanded structure is being used. 


mmiolniFileHandler Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following returns in this list. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERRINTERNALSYSTEM 

An internal system error was found. 

MMIOERR_NO_CORE 

Unable to allocate enough memory for the MMPMMMIO.INI data. 

MMIOERRINIOPEN 

Unable to open the MMPMMMIO.INI file. 

MMIOERR_INVALID_DLLNAME 

Unable to validate the DLL name. 

MMIOERR_INVALID_PROCEDURENAME 

Unable to validate the procedure name. 

MMIOERR_MATCH_NOT_FOUND 

Unable to find the I/O procedure to satisfy the input criteria. 


mmiolniFileHandler - Parameters 


pmminifileinfo (PMMINIFILEINFO) - input 

A pointer to the MMINIFILEINFO structure that contains the FOURCC code, DLL name, and the name of the I/O procedure. 
ulFlags (ULONG) - input 

Specifies options for the operation. Contains one of the following flags: 

MMIOJNSTALLPROC 

Adds an I/O procedure to the end of the MMPMMMIO.INI file. If an existing entry in the table matches the new 
entry, the new entry replaces the existing entry. An entry match is determined by specifying 0 or more of the 
match flags. If none are specified, the default is to match on the FOURCC code. 


MMIO_REMOVEPROC 

Deletes a matching entry from the MMPMMMIO.INI file. An entry match is determined by specifying 0 or more 
of the match flags. If none are specified, the default is to match on the FOURCC code. 


MMIO_FINDPROC 

Finds a matching entry from the MMPMMMIO.INI file. This fills in the remainder of the MMINIFILEINFO 
structure passed in the pmmin/fi/einfo parameter. An entry match is determined by specifying 0 or more of the 
match flags. If none are specified, the default is to match on the FOURCC. 

Note: If MMIO_FINDFIRST is set, then MMIO_FINDPROC does not default to the FOURCC. 

MMIO_MATCHFIRST 

Finds the first entry in the MMPMMMIO.INI file if no match flags are specified. Otherwise, it finds the first entry 
that matches the contents of the fields specified by the match flags. In either case, the MMINIFILEINFO 
structure is returned. 

MMIO_MATCHNEXT 

If no match flags are specified, this finds the next entry in the MMPMMMIO.INI file following the entry 
(MMINIFILEINFO structure) passed in the pmm/nifi/einfo parameter. If match flags are specified, this finds the 
next entry that matches the search criteria specified by the flags. In either case, the MMINIFILEINFO structure 
is returned. 

MM IO_MATCH FOURCC 

Use the FOURCC code ( fcc/OProc field of the MMINIFILEINFO structure) as a search criteria. 

MMIO_MATCHDLL 

Use the DLL Name ( szDLLName field of the MMINIFILEINFO structure) as a search criteria. 
MMIO_MATCHPROCEDURENAME 

Use the case-sensitive procedure name ( szProcName field of the MMINIFILEINFO structure) as a search 
criteria. 

MMIO_FULLPATH 

Use the drive or path given with the DLL name ( szDLLName field of the MMINIFILEINFO structure), 
otherwise use only the base file name. This allows DLLs with the same base name to be loaded from different 
directories. 

MMIO_EXTENDED_STRUCT 

This flag must be set for release 1.1 and later releases. It indicates the expanded structure is being used. 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following returns in this list. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERR_INTERNAL_SYSTEM 

An internal system error was found. 

MMIOERR_NO_CORE 

Unable to allocate enough memory for the MMPMMMIO.INI data. 

MMIOERR_INI_OPEN 

Unable to open the MMPMMMIO.INI file. 

MMIOERRINVALIDDLLNAME 

Unable to validate the DLL name. 

MMIOERRINVALIDPROCEDURENAME 

Unable to validate the procedure name. 

MMIOERR_MATCH_NOT_FOUND 

Unable to find the I/O procedure to satisfy the input criteria. 


mmiolniFileHandler - Remarks 


The MMPMMMIO.INI file is in the directory specified in the MMBASE environment variable. 

The DLL name ( szDLLName field) specified in the MMINIFILEINFO structure must follow the same naming conventions as the 
DosLoadModule function. If the DLL or procedure name is invalid, an error is returned. 

Any changes this function makes to the MMPMMMIO.INI file do not affect the MMIO internal data structures until the next time the DLL is 
loaded. This means that in the case of an addition, for example, the I/O procedure added is not active until the next time the MMIO.DLL is 
loaded. 

In a deletion, the entry is removed and the entire file is rewritten to prevent it from growing with deleted entries. This is due to the way the 
OS/2 functions handle deleting entries from INI files in general. They do not reuse deleted entries. 

If an error occurs during the loading of MMIO.DLL because the I/O procedure or procedure name cannot be validated, MMIO.DLL will still be 
loaded, but that particular I/O procedure will not be linked. The user must program for such situations. 

Note: When MMIO services builds its internal structures for the I/O procedures, it processes the MMPMMMIO.INI file as a stack. The result 
is, the last I/O procedure in the file is the first one called during processing. Thus, in the MMPMMMIO.INI file, enter last those I/O 
procedures that you want to process first. 


mmiolniFileHandler - Related Functions 


mmiolnstalllOProc 


mmiolniFileHandler - Example Code 


The following code illustrates how to modify the initialization file for MMIO services. 

MMINIFILEINFO mmlniFilelnf o; 

ULONG ulFlags = OL; 

ULONG rc; 


memset ( &mmIniFileInf o, * \ 0 * sizeof (MMINIFILEINFO) ); 
mmlniFilelnf o. fccIOProc = FOURCC_MYPROC; 

strncpy ( mmlniFilelnf o . szDLLName, "MYPROC", DLLNAME_S I ZE ); 
strncpy ( mmlniFilelnf o . szProcName, "MylOProc" , PROCNAME_SIZE ); 
ulFlags |= MMIO_INSTALLPROC; 

rc = mmiolniFileHandler ( &mmIniFileInf o, 

ulFlags) ; 

if (rc) 

/* error */ 
else 
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mmiolnstalllOProc 


mmiolnstalllOProc - Syntax 


This function installs an I/O procedure in the MMIO I/O procedure table, removes a procedure from the table, or finds a procedure when 
given its FOURCC identifier. 


#def ine INCL_MMIOOS2 
/(include <os2.h> 


FOURCC 

fccIOProc; 

/* 

Four- character 

code . * 

PMMIOPROC 

plOProc; 

/* 

IOProc address. 

. */ 

ULONG 

ulFlags; 

/* 

Flags. */ 


PMMIOPROC 

rc; 

/* 

Address of the 

IOProc . 


rc = mmiolnstalllOProc (fccIOProc, plOProc, 
ulFlags) ; 


mmiolnstalllOProc Parameter - fccIOProc 


fccIOProc (FOURCC) - input 

The four-character code of the I/O procedure to install, remove, or search for. 


mmiolnstalllOProc Parameter - plOProc 


plOProc (PMMIOPROC) - input 

If this function is being called to install an I/O procedure, then p/OProc must contain the address of the I/O procedure entry point. 
Otherwise, p/OProc must be NULL. 


mmiolnstalllOProc Parameter - ulFlags 


ulFlags (ULONG) - input 

Only one of the following flags can be set: 

MMIOJNSTALLPROC 

Installs an I/O procedure with the entry point specified in the p/OProc parameter and the FOURCC in the 
fcc/OProc parameter. 

MMIO_REMOVEPROC 

Removes an I/O procedure (that has the FOURCC specified in the fcc/OProc parameter) from the table of 
installed I/O procedures. 

MMIO_FINDPROC 

Finds a previously installed I/O procedure with the identifier with the FOURCC specified in the fcc/OProc 
parameter. 


mmiolnstalllOProc Return Value - rc 


rc (PMMIOPROC) - returns 

Upon successful completion, this function returns the address of the I/O procedure that was installed, removed, or searched for. if a 
failure occurs, NULL is returned. 


mmiolnstalllOProc - Parameters 


fcclOProc (FOURCC) - input 

The four-character code of the I/O procedure to install, remove, or search for. 
plOProc (PMMIOPROC) - input 

If this function is being called to install an I/O procedure, then p/OProc must contain the address of the I/O procedure entry point. 
Otherwise, p/OProc must be NULL. 

ulFlags (ULONG) - input 

Only one of the following flags can be set: 

MMIOJNSTALLPROC 

Installs an I/O procedure with the entry point specified in the p/OProc parameter and the FOURCC in the 
fcc/OProc parameter. 

MMIO_REMOVEPROC 

Removes an I/O procedure (that has the FOURCC specified in the fcc/OProc parameter) from the table of 
installed I/O procedures. 

MMIO_FINDPROC 

Finds a previously installed I/O procedure with the identifier with the FOURCC specified in the fcc/OProc 
parameter. 

rc (PMMIOPROC) - returns 

Upon successful completion, this function returns the address of the I/O procedure that was installed, removed, or searched for. If a 
failure occurs, NULL is returned. 


mmiolnstalllOProc - Remarks 


Installing an I/O procedure in the MMIO I/O procedure table allows mmioOpen to call that procedure if the file name given to mmioOpen is 
specified as being a FOURCC of the same type specified in the fcc/OProc parameter. For example, if you install a hypothetical I/O 
procedure with the fcc/OProc parameter equal to XYZ, and then call mmioOpen to open the file FOO.XYZ, setting the fcc/OProc field of 
MMIOINFO = XYZ, your I/O procedure is called to open and perform I/O on FOO.XYZ. 

mmiolnstalllOProc maintains a separate list of installed I/O procedures for each OS/2 application that uses MMIO services. If application X 
(or a DLL that application X calls) installs an I/O procedure identified as ABC, and application Y (or a DLL that Y calls) installs another I/O 
procedure identified as ABC, then MMIO services keeps separate entries in the I/O procedure table. Therefore, different applications can 
use the same I/O procedure identifier for different I/O procedures without conflict. Also, if an I/O procedure is implemented in a DLL and 
shared among several applications, each application must call mmiolnstalllOProc individually (or get the DLL to call it for the application), 
once to install the I/O procedure, and once to remove it from the table. 

If an application calls mmiolnstalllOProc more than once to register the same I/O procedure, then mmiolnstalllOProc must be called once 
with MMIO_REMOVEPROC for each time it is called with MMIOJNSTALLPROC. 

mmiolnstalllOProc will not prevent an application from installing two different I/O procedures with the same identifier, or installing an I/O 
procedure with the same identifier as a built-in I/O procedure (DOS, MEM, or BND). The most recently installed procedure takes 
precedence, and is the first one to get removed by MMIO_REMOVEPROC. 


mmiolnstalllOProc - Related Functions 


mmioSendMessage 


mmiolnstalllOProc - Example Code 


The following code illustrates how to install an lOProc. 


FOURCC 

PMMIOPROC 

ULONG 


fourccl ; 
plOProcl ; 
ulFlags; 


f ourccl= FOURCCJSAVE; 
ulFlags= MMIO_FINDPROC; 

pIOProcl= mmiolnstalllOProc (fourccl, plOProcl, ulFlags) ; 
if ( ! plOProcl ) 

/* WAVE I/O Procedure NOT FOUND */ 
else 

/* WAVE I/O Procedure FOUND */ 


The following is a procedure prototype for a standard I/O procedure call. 

LONG API ENTRY MMIOPROC (PVOID pmmioinfo, USHORT usMsg, 

LONG lParaml , LONG lParam2); 


The following code illustrates how to call a custom I/O procedure and what parameters are required. 

(LONG) lrc= IOProc (pmmioinfo, usMsg, lParaml, lParam2); 

The I/O procedure must return MMIOERR_UNSUPPORTED_MESSAGE if it or subsequent I/O procedures it has called through 
mmioSendMessage does not understand usMsg. 


mmiolnstalllOProc - Topics 
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mmioLoadCODECProc 


mmioLoadCODECProc - Syntax 


This function loads the CODEC Proc installed in the MMPMMMIO.INI file and returns the entry point. It is normally issued by the lOProc to 
access the CODEC Proc. 


#def ine INCL_MMIOOS2 
#def ine INCL_MMIO_CODEC 
ftinclude <os2.h> 


PCODECINIFILEINFO 

pCODECIniFilelnfo; 

/* 

Pointer to CODECINIFILEINFO . */ 

PHMODULE 

phMod; 

/* 

Pointer. */ 

ULONG 

ulFlags; 

/* 

Flags. */ 

PCODECPROC 

rc; 

/* 

Address of CODEC Proc. */ 


rc = mmioLoadCODECProc (pCODECIniFilelnfo, 
phMod, ulFlags) ; 


mmioLoadCODECProc Parameter - pCODECIniFilelnfo 


pCODECIniFilelnfo (PCODECINIFILEINFO) - input 

Pointer to a structure containing the CODEC information. The search parameters used to load the CODEC procedure are specified 
the u/F/ags parameter. 


mmioLoadCODECProc Parameter - phMod 


phMod (PHMODULE) - output 

Pointer to the returned module handle of the loaded CODEC procedure. 


mmioLoadCODECProc Parameter - ulFlags 


ulFlags (ULONG) - input 

Specifies options for the operation. Contains one of the following flags: 

MMIO_MATCHCOMPRESSTYPE 

Uses compression type ( u/CompressType field of CODECINIFILEINFO) as a search criteria for loading the 
CODEC procedure. 

MMIO_MATCHCOMPRESSSUBTYPE 

Uses the compression subtype ( u/CompressSubType field of CODECINIFILEINFO) as a search criteria for 
loading the CODEC procedure. 


MMIO_MATCHHWID 

Uses the hardware ID ( szHIV/D field of CODECINIFILEINFO) as a search criteria for loading the CODEC 
procedure. 

MMIO_MATCHCAPSFLAGS 

Uses the capability flags ( u/CapsF/ags field of CODECINIFILEINFO) as a search criteria for loading the 
CODEC procedure. This is not based on an exact match. If the target entry contains the flags, the match is 
satisfied. 


MMIO_SKIPMATCH 

Skips the search and loads the CODEC procedure using the DLL name ( szDLLName ) and Procedure name 
(szProcName) specified in the CODECINIFILEINFO structure. 

MMIO_MATCHDLL 

Uses the DLL Name ( szDLLName field of CODECINIFILEINFO) as a search criteria for loading the CODEC 
procedure. 

MMIO_MATCHFOURCC 

Uses the FOURCC code ( fee field of CODECINIFILEINFO) as a search criteria for loading the CODEC 
procedure. 

MMIO_MATCHPROCEDURENAME 

Uses the case-sensitive procedure name ( szProcName field of CODECINIFILEINFO) as a search criteria for 
loading the CODEC procedure. 


mmioLoadCODECProc Return Value - rc 


rc (PCODECPROC) - returns 

Upon successful completion, this function returns the address of the CODEC procedure that has been loaded. If a failure occurs, 
NULL is returned. 


mmioLoadCODECProc - Parameters 


pCODECIniFilelnfo (PCODECINIFILEINFO) - input 

Pointer to a structure containing the CODEC information. The search parameters used to load the CODEC procedure are specified in 
the u/F/ags parameter. 


phMod (PHMODULE) - output 

Pointer to the returned module handle of the loaded CODEC procedure. 
ulFlags (ULONG) - input 

Specifies options for the operation. Contains one of the following flags: 

MMIO_MATCHCOMPRESSTYPE 

Uses compression type ( u/CompressType field of CODECINIFILEINFO) as a search criteria for loading the 
CODEC procedure. 

MMIO_MATCHCOMPRESSSUBTYPE 

Uses the compression subtype ( u/CompressSubType field of CODECINIFILEINFO) as a search criteria for 
loading the CODEC procedure. 


MMIO_MATCHHWID 

Uses the hardware ID [szHW/D field of CODECINIFILEINFO) as a search criteria for loading the CODEC 
procedure. 

MMIO_MATCHCAPSFLAGS 

Uses the capability flags {u/CapsF/ags field of CODECINIFILEINFO) as a search criteria for loading the 
CODEC procedure. This is not based on an exact match. If the target entry contains the flags, the match is 
satisfied. 


MMIO_SKIPMATCH 

Skips the search and loads the CODEC procedure using the DLL name ( szDLLName ) and Procedure name 
(szProcName) specified in the CODECINIFILEINFO structure. 

MMIO_MATCHDLL 

Uses the DLL Name ( szDLLName field of CODECINIFILEINFO) as a search criteria for loading the CODEC 
procedure. 

MMIO_MATCHFOURCC 

Uses the FOURCC code ( fee field of CODECINIFILEINFO) as a search criteria for loading the CODEC 
procedure. 

MMIO_MATCHPROCEDURENAME 

Uses the case-sensitive procedure name ( szProcName field of CODECINIFILEINFO) as a search criteria for 
loading the CODEC procedure. 


rc (PCODECPROC) - returns 

Upon successful completion, this function returns the address of the CODEC procedure that has been loaded. If a failure occurs, 
NULL is returned. 


mmioLoadCODECProc - Remarks 


If none of the flags are specified, the default is to match on the FOURCC. 

The following is a procedure prototype for a standard CODEC procedure call. 

PCODECPROC APIENTRY mmioLoadCODECProc 

(PCODECINIFILEINFO pCODECIniFilelnfo, 
PHMODULE phMod, ULONG ulFlags) ; 

The following example shows how to call a CODEC Proc and the required parameters. 

LONG APIENTRY CODECProc (phCODEC, usMsg, lParaml, lParam2) 

Note that CODECProc represents the entry point of a CODEC DLL. 


phCODEC (PHCODEC) - Input/Output : 


Pointer to a CODEC instance handle returned by MMIOM_CODEC_OPEN. 

usMsg (USHORT) - Input 


The message that the CODEC Proc is asked to process. The following predefined messages are documented separately. 

MMIOM_CODEC_OPEN 

MMIOM_CODEC_CLOSE 

MM IOM_CODEC_COM PRESS 

MMIOM_CODEC_DECOMPRESS 

MMIOM_CODEC_QUERYNAME 

MMIOM_CODEC_QUERYNAMELENGTH 


lParaml (LONG) - input/output 


Specifies additional message information. 

!Param2 (LONG) - input/output 


Specifies additional message information. 


mmioLoadCODECProc - Example Code 


The following code illustrates how to load a CODEC Proc. 

CODECINIFILEINFO codecIniFilelnf o; 

HMODULE hMod; 

PCODECPROC pCODECProc ; 

ULONG rc, ulFlags; 

mmset ( ScodecIniFilelnf o, ' \\ sizeof (CODECINIFILEINFO) ) ; 
codecIniFilelnf o . ulStructlen = sizeof (CODECINIFILEINFO) ; 
codecIniFilelnf o. fee = FOURCC_MYPROC; 

codecIniFilelnf o.ulCompressType = COMPRESSTYPE_MYPROC; 
codecIniFilelnf o.ulCompressSubType = COMPRESSSUBTYPE_MYPROC; 
codecIniFilelnf o.ulCapsFlags = CODEC_CAN_DE COMPRESS, 
codecIniFilelnf o . szHWID = HWID_MYPROC; 
ulFlags = MMIO_MATCHFOURCC | 

MMIO_MATCHCOMPRESSTYPE | 

MMIO_MATCHCOMP RES S SUBTYPE | 

MMIO_MATCHHWID | 

MMIO_MATCHCAPSFLAGS | 

pCODECProc = mmioLoadCODECProc ( &codecIniFileInf o, &hMod, ulFlags) ; 

if ( IpCODECProc) 

/* error */ 
else 


mmioLoadCODECProc - Topics 
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mmioOpen 


mmioOpen - Syntax 


This function opens a file for unbuffered I/O or buffered I/O (including RIFF I/O). The file may be a DOS file, a memory file, or an element of 
a custom storage system (provided that a custom I/O procedure has been installed using mmiolnstalllOProc). 


#def ine INCL_MMIOOS2 
#include <os2.h> 


PSZ 

PMMIOINFO 

ULONG 

HMMIO 


pszFileName; /* 
pmmioinfo; /* 
ulOpenFlags; /* 
hmmio; /* 


File name. */ 

Pointer to MMIOINFO. */ 
Flags. */ 

MMIO file handle. */ 


hmmio = mmioOpen (pszFileName, pmmioinfo, ulOpenFlags); 


mmioOpen Parameter - pszFileName 


pszFileName (PSZ) - input 

The name of the file to open. If the fcc/OProc field of MMIOINFO is NULL, mmioOpen looks at the pszF'/eName parameter to figure 
out what kind of file to open, as follows: 

• If the pszF'/eName parameter does not contain a plus (+), the name is assumed to be that of a DOS file, which is opened 
using the file system file open process. 

• If the file name is of the form ABC.EXT+ELEMENTNAME, the extension EXT is assumed to identify an installed I/O 
procedure that is called to perform I/O on the file (see mmiolnstalllOProc). If the extension is BND, the system-provided 
BND I/O procedure processes the open. Note also that ELEMENTNAME could be of the form ABC. EXT followed by a 
plus sign (+). Parsing of the file name is done from right to left, so the first I/O procedure called belongs to the rightmost 
extension name that is followed by the +. The I/O procedure must be already installed and be able to further parse the file 
name, if required. The trailing separator character is stripped off by mmioOpen, and is not passed to the I/O procedure. 

• If the pszFZ/eName parameter is NULL, then the au//nfo field of MMIOINFO contains the DOS file handle, and I/O is 
performed on that file handle. The MMIO offset is the same as the DOS offset when mmioOpen is called. 

• The pszF/eName parameter cannot be longer than 260 bytes, including the terminating NULL, for a fully-qualified path 
name, or 256 bytes for an individual component name, including the terminating NULL. 


mmioOpen Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) - input 

A pointer to a caller-provided MMIOINFO structure containing extra parameters used by mmioOpen. Only certain values of the 
MMIOINFO structure may be used as input to the mmioOpen function. These fields are fcc/OProc , p/OProc , cchBuffer, pchBuffer , 
au//nfo , and u/Trans/ate. fcc/OProc and p/OProc are used if you wish to identify the I/O procedure to be used, rather than allowing 
MMIO to determine the appropriate I/O procedure. cchBuffer and pchBuffer are used for buffered access. au//r>fo can contain a 
media type which restricts the open to I/O procedures of that type. u/Trans/ate is used to specify whether or not translation of header 
and data is performed. 

The pmmioinfo parameter can be NULL if the default values of the fields of MMIOINFO are sufficient. All unused fields must be set to 
0, including reserved fields. (The easiest way to do this is to fill the structure with NULL bytes before setting the desired fields.) See 
the MMIOINFO data structure for more information. mmioOpen will modify the u/ErrorPet field of MMIOINFO if an error is 
encountered. 


mmioOpen Parameter - ulOpenFlags 


ulOpenFlags (ULONG) - input 

Contains one or more of the following flags: 

Note: The MMIO_READ, MMIO_WRITE, and MMIO_READWRITE flags are mutually exclusive. 

MMIO_READ 

Opens the file for reading only. This is the default behavior if MMIO_WRITE and MMIO_READWRITE are not 
specified. Flowever, the flag is not automatically set in the default case. 

MMIO_WRITE 

Opens the file for writing. You should not read from a file opened in this way. 

MMIO_READWRITE 

Opens the file for both reading and writing. 

Note: To save a wave file, you must open the file with the MMIO_READWRITE flag. After the data is written, 
the I/O procedure will need to descend back into the wave chunk-a process that requires read support. 

MMIO_BUFSHARED 

Requests that if MMIO services allocates the I/O buffer, it does so from shared memory. 

MMIO_VERTBAR 

Requests that the vertical bar symbol (|) rather than the plus sign (+) be used as a file separator. 

MMIO_EXCLUSIVE 

Opens the file with exclusive mode, denying other processes both read and write access to the file. 
mmioOpen fails if the file has been opened in any other mode for read or write access, even by the current 
process. 

MMIO_DENYWRITE 

Opens the file and denies other processes write access. mmioOpen fails if the file has been opened in 
compatibility or for write access by any other process. 

MMIO_DENYREAD 

Opens the file and denies other processes read access. mmioOpen fails if the file has been opened in 
compatibility or for read access by any other process. 

MMIO_DENYNONE 

Opens the file and denies other processes read access. mmioOpen fails if the file has been opened in 
compatibility or for read access by any other process. This is the default if no share mode flags are defined. 

MMIO_CREATE 

Directs mmioOpen to create a new file. If the file already exists, it is truncated to 0 length. For a memory file, 
MMIO_CREATE indicates the end of the file is initially at the start of the buffer. 

MMIO_DELETE 

Directs mmioOpen to delete the file. The pszF/ZeName parameter should not be NULL. The return value will 
be TRUE (sent to hmm/o ) if the file was deleted successfully, FALSE otherwise. Do not call mmioClose if 
MMIO_DELETE has been specified. All other flags are ignored if MMIO_DELETE is specified. 


MMIO_ALLOCBUF 

Directs mmioOpen to allocate an I/O buffer. If the cchBuffer field of MMIOINFO is 0, then a default buffer size 
(specified by the constant MMIO_DEFAULTBUFFER) is used. If the caller provides an I/O buffer, then 
MMIO_ALLOCBUF should not be specified. 

MMIO_APPEND 

Directs mmioOpen to allow appending to the end of the file. This will cause the logical file pointer to be 
positioned at the end of file when the open process completes. The open fails if both MMIO_CREATE and 
MMIO_APPEND are set. In the case of a BND element, this flag allows the element to expand past its existing 
fixed boundary by deleting the existing element and rewriting it at the end of a compound-file resource group 
(CGRP). 

MMIO_NOIDENTIFY 

Directs mmioOpen to directly open the file without attempting to automatically identify the file. An automatic 
identify is the default for this function. 


mmioOpen Return Value - hmmio 


hmmio (PIMMIO) - returns 

A handle is returned to use with further calls to MMIO functions to perform I/O. This handle is not a file system handle. Do not use this 
with such operations as OS/2 file system read, or write. 

NULL is returned if the file cannot be opened. See the exception for the preceding u/OpenF/ags parameter flag MMIO_DELETE. If 
the pmmioinfo parameter is not NULL, the u/ErrorPet field of its MMIOINFO structure will contain extended error information 
returned by the I/O procedure. If delete fails, u/ErrorPet contains MMIOERR_DELETE_FAILED. The error return can also be queried 
by calling the mmioGetLastError function. See Return Codes for a description of MMIO Manager error codes. 


mmioOpen - Parameters 


pszFileName (PSZ) - input 

The name of the file to open. If the fcc/OProc field of MMIOINFO is NULL, mmioOpen looks at the pszF/ZeName parameter to figure 
out what kind of file to open, as follows: 

• If the pszF/ZeName parameter does not contain a plus (+), the name is assumed to be that of a DOS file, which is opened 
using the file system file open process. 

• If the file name is of the form ABC.EXT+ELEMENTNAME, the extension EXT is assumed to identify an installed I/O 
procedure that is called to perform I/O on the file (see mmiolnstalllOProc). If the extension is BND, the system-provided 
BND I/O procedure processes the open. Note also that ELEMENTNAME could be of the form ABC. EXT followed by a 
plus sign (+). Parsing of the file name is done from right to left, so the first I/O procedure called belongs to the rightmost 
extension name that is followed by the +. The I/O procedure must be already installed and be able to further parse the file 
name, if required. The trailing separator character is stripped off by mmioOpen, and is not passed to the I/O procedure. 

• If the pszFi/e/Mame parameter is NULL, then the au/Znfo field of MMIOINFO contains the DOS file handle, and I/O is 
performed on that file handle. The MMIO offset is the same as the DOS offset when mmioOpen is called. 

• The pszF/ZeName parameter cannot be longer than 260 bytes, including the terminating NULL, for a fully-qualified path 
name, or 256 bytes for an individual component name, including the terminating NULL. 

pmmioinfo (PMMIOINFO) - input 

A pointer to a caller-provided MMIOINFO structure containing extra parameters used by mmioOpen. Only certain values of the 
MMIOINFO structure may be used as input to the mmioOpen function. These fields are fcc/OProc , p/OProc , cchBuffer , pchBuffer , 
auZ/nfo , and u/Trans/ate. fcc/OProc and p/OProc are used if you wish to identify the I/O procedure to be used, rather than allowing 
MMIO to determine the appropriate I/O procedure. cchBuffer and pchBuffer are used for buffered access. au/Znfo can contain a 
media type which restricts the open to I/O procedures of that type. u/Trans/ate is used to specify whether or not translation of header 
and data is performed. 

The pmmioinfo parameter can be NULL if the default values of the fields of MMIOINFO are sufficient. All unused fields must be set to 


0, including reserved fields. (The easiest way to do this is to fill the structure with NULL bytes before setting the desired fields.) See 
the MMIOINFO data structure for more information. mmioOpen will modify the u/ErrorHet field of MMIOINFO if an error is 
encountered. 


ulOpenFlags (ULONG) - input 

Contains one or more of the following flags: 

Note: The MMIO_READ, MMIO_WRITE, and MMIO_READWRITE flags are mutually exclusive. 


MMIO_READ 

Opens the file for reading only. This is the default behavior if MMIO_WRITE and MMIO_READWRITE are not 
specified. Flowever, the flag is not automatically set in the default case. 

MMIO_WRITE 

Opens the file for writing. You should not read from a file opened in this way. 

MMIO_READWRITE 

Opens the file for both reading and writing. 

Note: To save a wave file, you must open the file with the MMIO_READWRITE flag. After the data is written, 
the I/O procedure will need to descend back into the wave chunk-a process that requires read support. 


MMIO_BUFSHARED 

Requests that if MMIO services allocates the I/O buffer, it does so from shared memory. 


MMIO_VERTBAR 

Requests that the vertical bar symbol (|) rather than the plus sign (+) be used as a file separator. 

MMIO_EXCLUSIVE 

Opens the file with exclusive mode, denying other processes both read and write access to the file. 
mmioOpen fails if the file has been opened in any other mode for read or write access, even by the current 
process. 

MMIO_DENYWRITE 

Opens the file and denies other processes write access. mmioOpen fails if the file has been opened in 
compatibility or for write access by any other process. 

MMIO_DENYREAD 

Opens the file and denies other processes read access. mmioOpen fails if the file has been opened in 
compatibility or for read access by any other process. 

MMIO_DENYNONE 

Opens the file and denies other processes read access. mmioOpen fails if the file has been opened in 
compatibility or for read access by any other process. This is the default if no share mode flags are defined. 

MMIO_CREATE 

Directs mmioOpen to create a new file. If the file already exists, it is truncated to 0 length. For a memory file, 
MMIO_CREATE indicates the end of the file is initially at the start of the buffer. 

MMIO_DELETE 

Directs mmioOpen to delete the file. The pszH/eName parameter should not be NULL. The return value will 
be TRUE (sent to hmm/o ) if the file was deleted successfully, FALSE otherwise. Do not call mmioClose if 
MMIO_DELETE has been specified. All other flags are ignored if MMIO_DELETE is specified. 

MMIO_ALLOCBUF 

Directs mmioOpen to allocate an I/O buffer. If the cchBuffer field of MMIOINFO is 0, then a default buffer size 
(specified by the constant MMIO_DEFAULTBUFFER) is used. If the caller provides an I/O buffer, then 
MMIO_ALLOCBUF should not be specified. 

MMIO_APPEND 

Directs mmioOpen to allow appending to the end of the file. This will cause the logical file pointer to be 
positioned at the end of file when the open process completes. The open fails if both MMIO_CREATE and 
MMIO_APPEND are set. In the case of a BND element, this flag allows the element to expand past its existing 
fixed boundary by deleting the existing element and rewriting it at the end of a compound-file resource group 
(CGRP). 

MMIO_NOIDENTIFY 

Directs mmioOpen to directly open the file without attempting to automatically identify the file. An automatic 
identify is the default for this function. 


hmmio (FIMMIO) - returns 

A handle is returned to use with further calls to MMIO functions to perform I/O. This handle is not a file system handle. Do not use this 
with such operations as OS/2 file system read, or write. 


NULL is returned if the file cannot be opened. See the exception for the preceding u/OpenF/ags parameter flag MMIO_DELETE. If 
the pmmio/nfo parameter is not NULL, the u/ErrorPet field of its MMIOINFO structure will contain extended error information 
returned by the I/O procedure. If delete fails, u/ErrorPet contains MMIOERR_DELETE_FAILED. The error return can also be queried 
by calling the mmioGetLastError function. See Return Codes for a description of MM 10 Manager error codes. 


mmioOpen - Remarks 


If the pmmioinfo parameter is provided the following fields must be filled in by the caller as described: 

fcc/OProc - If this field is not NULL, it is the four character code of an installed I/O procedure that will handle I/O. If fcc/OProc and p/OProc 
are NULL, mmioOpen determines which I/O procedure to use based on the syntax of the pszFZ/eName parameter. (See description of 
pszF/e/Vame .) If fcc/OProc is NULL, but p/OProc is not NULL, the custom I/O procedure [p/OProc ) is used. This I/O procedure does not 
need to be installed using mmiolnstalllOProc. 

The following I/O procedure identifiers are defined: 

pszFZ/eName is assumed to be either the name of a DOS file (which is to be opened using the 
file system opening procedure), or au/Znfo contains the DOS file handle of an open file handle 
(directed to a PSZ). 

A RIFF compound file element is opened. This procedure calls mmioCFOpen if necessary to 
read the CTOC into memory before the element can be accessed. 

If MMIO_CREATE or MMIO_APPEND is specified when opening an element, the system 
automatically accesses the element as exclusive until the element is closed. 

A memory file is opened. The pszF/ZeName parameter should be NULL. There are two ways to 
set up a memory file: 

1 . The pchBuffer field points to a caller-supplied memory buffer, and the cchBuffer 
field indicates the size of the buffer. The memory file can be read and written like an 
ordinary file, but the file can not be expanded larger than the number of bytes 
specified in cchBuffer. If the MMIO_CREATE flag is specified, the end of the file is 
initially at the beginning of the buffer. If MMIO_CREATE is NULL, the user specifies 
in au/ZnfofZJ the number of bytes of data in the memory buffer. For the default case, 
where au/fnfo/'ZJ is 0, the end of the file is set to the end of the buffer. 

2. mmioOpen can allocate the memory block for the memory file. The cchBuffer field is 
the desired initial size of the memory I/O buffer. The au//nfo{OJ field must be the 
number of bytes by which to expand the memory file if the initial buffer becomes 
filled. The MMIO_CREATE flag must be specified. The end of the file is initially at the 
beginning of the buffer, and if the memory file must be expanded, it is expanded at 
least au//r>fo{OJ bytes at a time. If auf/nfofOJ is 0, the buffer cannot expand. There is 
no default for cchBuffer when used to open a memory file. 

The p/OProc field uses a custom I/O procedure defined in this field. Set the fcc/OProc field to NULL, and set the p/OProc field to the 
address of the custom I/O procedure to use. Otherwise, p/OProc must be zero. 

cchBuffer specifies the size of the memory block to use as an I/O buffer or as a memory file. See descriptions of pchBuffer and the 
MMIO_ALLOCBUF flag for more information. 

The pchBuffer field points to a caller-provided memory buffer to use as an I/O buffer or as a memory file. The cchBuffer field must be the 
size of the buffer. If the caller-provided memory buffer is not provided, pchBuffer must be NULL. 

To open a memory file that performs I/O on an already allocated memory block, set the pszFZ/eName parameter to NULL, the fcc/OProc 
field to FOURCC_MEM, the pchBuffer field to point to the memory buffer, the cchBuffer field to the size of the memory buffer, the 
u/OpenF/ags parameter to MMIO_READWRITE (plus MMIO_CREATE if the memory file is initially empty), and set all other fields of the 
MMIOINFO structure passed in the pmmioinfo parameter to zero. 

For example, to open a memory file that is initially 32KB in size, but can be expanded at least 16KB at a time: 

1. Set auf/nfofOJ = 1 6K 

2. Set cBytes =16K 

3. pszF//e/Vame to NULL 

4. Set fcc/OProc to FOURCC_MEM 


FOURCC_DOS 


FOURCC_BND 


FOURCC_MEM 


5. Set u/OpenF/ags to indicate MMIO_READWRITE plus MMIO_CREATE 

6. Set other fields of pmmioinfo to zero 

Initially this file will be empty. 

A system-allocated memory buffer must be opened as MMIO_READWRITE, which is the default for that case. If this does not happen, the 
open-a-memory file process fails. 

If both a user buffer is specified, and an expansion size is requested, the open-a-memory file process fails because it is not possible to later 
expand the buffer size in this situation. 

As with DOS file handles, different applications cannot share a single hmm/o . In other words, MMIO handles (HMMIO) are unique to a 
process. 


mmioOpen - Related Functions 


mmioClose 

mmioRead 

mmioSeek 

mmioWrite 


mmioOpen - Example Code 


The following code illustrates how to open a file for I/O. 

HMMIO hmmiol; 

MMIOINFO mmioinfo; 

ULONG ulFlags = OL; 


memset ( &mmioinfo, ' \0', sizeof (MMIOINFO) ); 
mmioinfo . fccIOProc = FOURCC_WAVE; 
ulFlags |= MMIO_READ | MMIO_DENYNONE ; 

hmmiol = mmioOpen ( " sounds . bnd+t rain . wav" , &mmioinfo, ulFlags); 
if ( ! hmmiol ) 

/* error */ 
else 


mmioOpen - Topics 
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mmioQueryCODECName 


mmioQueryCODECName - Syntax 

This function returns the CODEC procedure name. 


#def ine INCL_MMIOOS2 
#def ine INCL_MMIO_CODEC 
#include <os2.h> 


PCODECINIFILEINFO 

pCODECIniFileinfo; 

/* 

Pointer. */ 

PSZ 

pszCODECName; 

/* 

Pointer. */ 

PULONG 

pulBytesRead; 

/* 

Byte size read. */ 

ULONG 

rc; 

/* 

Return codes. */ 


rc = mmioQueryCODECName (pCODECIniFileinfo, 
pszCODECName, pulBytesRead) ; 


mmioQueryCODECName Parameter - pCODECIniFileinfo 


pCODECIniFileinfo (PCODECINIFILEINFO) - input 

Pointer to the CODECINIFILEINFO data structure containing the CODEC information. Only the fee , u/CompressType , 
u/CompressSubType , szHIV/D , and u/CapsF/ags fields of the structure are used to identify a CODEC procedure. 


mmioQueryCODECName Parameter - pszCODECName 


pszCODECName (PSZ) - output 

Pointer to the CODEC name. The function fills in the CODEC name associated with the specified CODEC procedure, up to 
pu/BytesRead bytes. Make sure the buffer is at least one byte long. 


mmioQueryCODECName Parameter - pulBytesRead 


pulBytesRead (PULONG) - in/out 

On input, specifies the size in bytes of the pszCODECName . On output, returns the number of bytes read into the 
pszCODECName . 


mmioQueryCODECName Return Value - rc 


rc (ULONG) - returns 
Return codes. 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the returns in this list. 

MMIO_INVALID_PARAMETER 

An invalid parameter was passed. 


mmioQueryCODECName - Parameters 


pCODECIniFileinfo (PCODECINIFILEINFO) - input 

Pointer to the CODECINIFILEINFO data structure containing the CODEC information. Only the fee , u/CompressType , 
u/CompressSubType , szHI/V/D , and u/CapsF/ags fields of the structure are used to identify a CODEC procedure. 

pszCODECName (PSZ) - output 

Pointer to the CODEC name. The function fills in the CODEC name associated with the specified CODEC procedure, up to 
pu/BytesRead bytes. Make sure the buffer is at least one byte long. 

pulBytesRead (PULONG) - in/out 

On input, specifies the size in bytes of the pszCODECName . On output, returns the number of bytes read into the 
pszCODECName . 

rc (ULONG) - returns 
Return codes. 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the returns in this list. 

MMIO_INVALID_PARAMETER 

An invalid parameter was passed. 


mmioQueryCODECName - Example Code 


The following code illustrates how to obtain the name of the CODEC procedure. 

CODECINIFILFO codecIniFilelnf o; 

PULONG pulBytesRead; 

PSZ pszCODECName; 

ULONG rc; 


mmset ( &codecIniFileInf o, ' \0', sizeof (CODECINIFILEINFO) ; 
codecIniFilelnf o . ulStructLen = sizeof (CODECINIFILEINFO) ; 
codecIniFilelnf o. fee = FOURCC MYPROC; 

codecIniFilelnf o . ulCompressType = COMP RES S_TYPE_MYPROC 
codecIniFilelnf o.ulCompressSubType = COMPRESSSUBTYPE_MYPROC 


codec IniFile Inf o . ulCapsFlags = CODEC_CAN_DECOMPRESS; 
codecIniFilelnf o . szHWID = MYPROC; 

rc = mmioQueryCODECNameLength ( &codecIniFileInf o, 
pulBytesRead) ; 
if (rc) 

/* error */ 
else 

pszCODECName = malloc ( *pulBytesRead fsizeof (char) ) ; 
rc = mmioQueryCODECName ( ScodecIniFilelnf o, 

pszCODECName, 
pulBytesRead) ; 


if (rc) 

/* error */ 
else 
} 


mmioQueryCODECName - Topics 
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mmioQueryCODECNameLength 


mmioQueryCODECNameLength - Syntax 


This function returns the length of the CODEC procedure name. 


#def ine INCL_MMIOOS2 
#def ine INCL_MMIO_CODEC 
#include <os2.h> 


PCODEC INI FILE INFO 

pCODECIniFileinf o; 

/* 

Pointer to CODECINIFILEINFO structure 

PULONG 

pulNameLength; 

/* 

# of bytes. */ 

ULONG 

rc ; 

/* 

Return codes. */ 


rc = mmioQueryCODECNameLength (pCODECIniFileinf o, 
pulNameLength) ; 


mmioQueryCODECNameLength Parameter 


pCODECIniFileinfo 


pCODECIniFileinfo (PCODECINIFILEINFO) - input 

Pointer to the CODECINIFILEINFO data structure containing the CODEC information. Only the fee , u/CompressType , 
u/CompressSubType , szHI/V/D , and u/CapsF/ags fields of the structure are used to identify a CODEC procedure. 


mmioQueryCODECNameLength Parameter - pulNameLength 


pulNameLength (PULONG) - output 

Number of bytes in the CODEC procedure name is returned. The returned length does not include the NULL terminating character. 


mmioQueryCODECNameLength Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following returns in this list. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 


mmioQueryCODECNameLength - Parameters 


pCODECIniFileinfo (PCODECINIFILEINFO) - input 

Pointer to the CODECINIFILEINFO data structure containing the CODEC information. Only the fee , u/CompressType , 
u/CompressSubType , szHIV/D , and u/CapsF/ags fields of the structure are used to identify a CODEC procedure. 

pulNameLength (PULONG) - output 

Number of bytes in the CODEC procedure name is returned. The returned length does not include the NULL terminating character, 
rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following returns in this list. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 


mmioQueryCODECNameLength - Example Code 


The following code illustrates how to obtain the length of the CODEC procedure name. 

CODECINIFILFO CODECIniFilelnf o; 

PULONG pulNameLength; 


mmset ( &CODECIniFileInf o, ' \ 0 1 , sizeof (CODECINIFILEINFO) ); 
CODECIniFilelnf o . ulStructLen = sizeof (CODECINIFILEINFO) ; 
CODECIniFilelnf o. fee = FOURCC_MYPROC; 

CODECIniFilelnf o.ulCompressType = COMPRESSTYPE_MYPROC; 
CODECIniFilelnf o.ulCompressSubType = COMPRESSSUBTYPE_MYPROC; 
CODECIniFilelnf o.ulMediaType = MEDIATYPE_MYPROC ; 
CODECIniFilelnf o.ulCapsFlags = CODEC_CAN_DE COMPRESS; 
CODECIniFilelnf o . szHWID = HWID_MYPROC 
re = mmioQueryCODECNameLength ( &CODECIniFileInf o, 
pulNameLength) ; 

if (re) 

/* error */ 
else 


mmioQueryCODECNameLength - Topics 
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mmioQueryFormatCount 


mmioQueryFormatCount - Syntax 


This function provides the number of I/O procedures that match the specified data format. 


#def ine INCL_MMIOOS2 
/(include <os2.h> 


PMMFORMAT INFO 

pmmf ormatinf o; 

/* 

Indicates 

field type. */ 

PLONG 

plNumFormats ; 

/* 

Number of 

supported formats 

ULONG 

ulReserved; 

/* 

Reserved . 

*/ 

ULONG 

ulFlags; 

/* 

Reserved . 

*/ 

ULONG 

rc ; 

/* 

Return codes. */ 


rc = mmioQueryFormatCount (pmmf ormatinf o, plNumFormats, 


ulReserved, ulFlags) ; 


mmioQueryFormatCount Parameter - pmmformatinfo 


pmmformatinfo (PMMFORMATINFO) - input 

Indicates a specific lOProc that is to be queried on the basis of whether the fcc/OProc field or the u/Med/aType field or both are 
specified in the structure. If neither is set, all I/O procedures are counted (queried). 


mmioQueryFormatCount Parameter - pINumFormats 


pINumFormats (PLONG) - output 

Pointer to a LONG. Returns the number of formats supported. 


mmioQueryFormatCount Parameter - ulReserved 


ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioQueryFormatCount Parameter - ulFlags 


ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioQueryFormatCount Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following returns in this list. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 


MMIOERR_INTERNAL_SYSTEM 

An internal system error occurred. 


mmioQueryFormatCount - Parameters 


pmmformatinfo (PMMFORMATINFO) - input 

Indicates a specific lOProc that is to be queried on the basis of whether the fcc/OProc field or the u/Med/aType field or both are 
specified in the structure. If neither is set, all I/O procedures are counted (queried). 

pINumFormats (PLONG) - output 

Pointer to a LONG. Returns the number of formats supported. 

ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 

ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 

rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following returns in this list. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERRINTERNALSYSTEM 

An internal system error occurred. 


mmioQueryFormatCount - Remarks 


An application can use this function to query the number of formats supported, and then call mmioGetFormats with the correct size of 
pFormat/nfoL/st to obtain descriptive information in MMFORMATINFO structures. 


mmioQueryFormatCount - Related Functions 


mmioGetFormats 


mmioQueryFormatCount - Example Code 


The following code illustrates how to obtain the number of lOProcs matching the specified format data. 


MMFORMATINFO mmf ormatinf o; 
LONG INumFormats; 

ULONG ulReserved = OL; 
ULONG ulFlags = OL; 

ULONG rc; 


memset ( &mmf ormatinf o, ' \0', sizeof (MMFORMATINFO) ); 
mmf ormatinf o.ulMediaType |= MMIO_MEDIATYPE_AUDIO; 
mmf ormatinf o . ulStructLen=sizeof (MMFORMATINFO) ; 

rc = mmioQueryFormatCount ( &mmf ormatinf o, 

& INumFormats, 
ulReserved, 
ulFlags) ; 

if (rc) 

/* error */ 
else 


mmioQueryFormatCount - Topics 
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mmioQueryFleaderLength 


mmioQueryFleaderLength - Syntax 


This function determines the size of the header for the opened file. It sends MMIOM_QUERYFIEADERLENGTFI to the I/O procedure. The 
file was opened using mmioOpen. 


#def ine INCL_MMIOOS2 
ftinclude <os2.h> 


HMMIO 

hmmio; 

/* 

Open file 

handle. */ 

PLONG 

plHeaderLength; 

/* 

Size of the header. */ 

ULONG 

ulReserved; 

/* 

Reserved . 

*/ 

ULONG 

ulFlags; 

/* 

Reserved . 

*/ 

ULONG 

rc ; 

/* 

Return codes. */ 


rc = mmioQueryHeaderLength (hmmio, plHeaderLength, 
ulReserved, ulFlags) ; 


mmioQueryHeaderLength Parameter - hmmio 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


mmioQueryHeaderLength Parameter - plHeaderLength 


plHeaderLength (PLONG) - output 

Pointer to a LONG. The size of the header in bytes is returned. If the MMIO_TRANSLATEHEADER flag was set in the u/Trans/ate 
field of MMIOINFO on mmioOpen, it is the size of one of the standard headers listed below. Otherwise, it is the size of a native 
(untranslated) header for this type of file. 


mmioQueryHeaderLength Parameter - ulReserved 


ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioQueryHeaderLength Parameter - ulFlags 


ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioQueryHeaderLength Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 
MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The specified file is not a media file format type. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 


MMIOERR_SEEK_FAILED 

A seek operation prior to a write- or read-advance operation failed. 


mmioQueryHeaderLength - Parameters 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 

plHeaderLength (PLONG) - output 

Pointer to a LONG. The size of the header in bytes is returned. If the MMIO_TRANSLATEHEADER flag was set in the u/Trans/ate 
field of MMIOINFO on mmioOpen, it is the size of one of the standard headers listed below. Otherwise, it is the size of a native 
(untranslated) header for this type of file. 

ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 

ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 

rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The specified file is not a media file format type. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERR_SEEK_FAILED 

A seek operation prior to a write- or read-advance operation failed. 


mmioQueryHeaderLength - Remarks 


The application calls mmioQueryFleaderLength first to determine the buffer size that is needed by mmioGetFleader to obtain header data. 
This is required because headers for different formats are variable in length. 

The header is different for each Media Type. The currently defined values for each u/Med/aType (MMIOINFO structure) follow: 
MMIO_MEDIATYPE_IMAGE 

The data represents a still image. Images use MMIMAGEFIEADER as the media structure. 

MMIO_MEDIATYPE_AUDIO 

The data represents digital audio. Digital-audio data streams use MMAUDIOFIEADER as the media structure. 
MMIO_MEDIATYPE_MIDI 

The data represents MIDI streams. MIDI data streams use MMMIDIFIEADER as the media structure. 
MMIO_MEDIATYPE_DIGITALVIDEO 

The data represents digital video. Digital video data streams use MMVIDEOFIEADER as the media structure. 
MMIO_MEDIATYPE_MOVIE 

The data represents a movie. Movie data uses MMMOVIEFIEADER as the media structure. 


mmioQueryHeaderLength - Related Functions 


mmioGetlnfo 

mmioSetlnfo 


mmioQueryFleaderLength - Example Code 


The following code illustrates how to determine the header size. 

HMMIO hmmiol; 

LONG lHeaderLength; 

ULONG ulReserved = OL; 

ULONG ulFlags = OL; 

ULONG rc; 


rc = mmioQueryHeaderLength ( 


if (rc) 

/* error */ 
else 


hmmiol , 

& lHeaderLength, 
ulReserved, 
ulFlags) ; 


mmioQueryFleaderLength - Topics 
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mmioQuerylOProcModuleHandle 


mmioQuerylOProcModuleHandle - Syntax 


This function provides the module handle of an I/O procedure's DLL. This handle must be used to retrieve resources from the DLL. 


#def ine INCL_MMIOOS2 
#include <os2.h> 


PMMIOPROC 

plOProc; 

/* 

Specifies entry point 

PHMODULE 

phmodlOProc; 

/* 

Pointer. */ 

ULONG 

rc; 

/* 

Return codes. */ 


rc = mmioQuerylOProcModuleHandle (plOProc, 
phmodlOProc) ; 


mmioQuerylOProcModuleHandle Parameter - plOProc 


plOProc (PMMIOPROC) - input 

Indicates a specific entry point of an I/O procedure for which the DLL module handle is to be retrieved. That is, the address of the 
DLL's entry point, directed to a PMMIOPROC. 


mmioQuerylOProcModuleHandle Parameter - phmodlOProc 


phmodlOProc (PHMODULE) - output 

Pointer to a PHMODULE. Returns the module handle to the DLL. 


mmioQuerylOProcModuleHandle Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following returns in this list. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERR_INTERNAL_SYSTEM 

An internal system error occurred. 


mmioQuerylOProcModuleHandle - Parameters 


plOProc (PMMIOPROC) - input 

Indicates a specific entry point of an I/O procedure for which the DLL module handle is to be retrieved. That is, the address of the 
DLL's entry point, directed to a PMMIOPROC. 

phmodlOProc (PHMODULE) - output 

Pointer to a PHMODULE. Returns the module handle to the DLL. 

rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The function failed for a reason different from any of the following returns in this list. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERR_INTERNAL_SYSTEM 

An internal system error occurred. 


mmioQuerylOProcModuleHandle - Remarks 


The mmioQuerylOProcModuleHandle function can only provide the handle to the DLL if it was loaded by MMIO from the MMPMMMIO.INI 
file. 


mmioQuerylOProcModuleHandle - Related Functions 


mmioGetlnfo 

mmioSetlnfo 


mmioQuerylOProcModuleHandle - Example Code 


The following code illustrates how to obtain the module handle of an lOProc's DLL. 

HMODULE hmodlOProc; 

ULONG rc; 


rc = mmioQuerylOProcModuleHandle ( (PMMIOPROC) &MyIOProc, &hmodIOProc) 
if (rc) 

/* error */ 
else 


The following is a procedure prototype for a standard I/O procedure call. 

LONG APIENTRY MMIOPROC (PVOID pmmioinfo, USHORT usMsg, 

LONG lParaml, LONG lParam2); 


mmioQuerylOProcModuleHandle - Topics 


Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Example Code 
Related Functions 
Glossary 


mmioRead 


mmioRead - Syntax 


This function reads from a file opened by mmioOpen and updates the file position. 


#def ine INCL_MMIOOS2 
#include <os2.h> 


HMMIO 

hmmio; 

/* 

PCHAR 

pchBuffer; 

/* 

LONG 

cBytes; 

/* 

LONG 

rc; 

/* 


Open file handle. */ 
Buffer to read to. */ 
Number of bytes read. */ 
Return codes. */ 


rc = mmioRead (hmmio, pchBuffer, cBytes) ; 


mmioRead Parameter - hmmio 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


mmioRead Parameter - pchBuffer 


pchBuffer (PCHAR) - input 
The buffer to read to. 


mmioRead Parameter - cBytes 


cBytes (LONG) - input 

The number of bytes to read from the file into the pchBuffer parameter. 


mmioRead Return Value - rc 


rc (LONG) - returns 

Returns the number of bytes actually read. If no more bytes can be read because the end of file has been reached, 0 is returned. If 
an error occurs, MMIO_ERROR is returned. A call to mmioGetLastError might return one of the following errors: 

MMIOERR_WRITE_ONLY_FILE 

File not opened in Read mode. 

MMIOERR_READ_FAILED 

Unable to read; probable hardware error. 

MMIOERR_WRITE_FAILED 

Writing to a full buffer before trying to read the next buffer failed. 

MMIOERR_SEEK_FAILED 

Unable to seek; probable hardware error. 

MMIOERRINVALIDBUFFERLENGTFI 

The buffer length is invalid. 

MMIOERR_NO_BUFFER_ALLOCATED 

Write operation expected a buffer but none was allocated. 


mmioRead - Parameters 


hmmio (FIMMIO) - input 

The open file handle returned by mmioOpen. 

pchBuffer (PCFIAR) - input 
The buffer to read to. 

cBytes (LONG) - input 

The number of bytes to read from the file into the pchBuffer parameter, 
rc (LONG) - returns 

Returns the number of bytes actually read. If no more bytes can be read because the end of file has been reached, 0 is returned. If 
an error occurs, MMIO_ERROR is returned. A call to mmioGetLastError might return one of the following errors: 

MMIOERR_WRITE_ONLY_FILE 

File not opened in Read mode. 

MMIOERR_READ_FAILED 

Unable to read; probable hardware error. 

MMIOERR_WRITE_FAILED 

Writing to a full buffer before trying to read the next buffer failed. 


MMIOERR SEEK FAILED 


Unable to seek; probable hardware error. 


MMIOERRINVALIDBUFFERLENGTH 

The buffer length is invalid. 

MMIOERR_NO_BUFFER_ALLOCATED 

Write operation expected a buffer but none was allocated. 


mmioRead - Remarks 


If the MMIO_TRANSLATEDATA flag was in the u/Trans/ate field of the MMIOINFO structure when the file was opened, the data will be 
translated from its native encoding scheme to the encoding scheme of the standard presentation format for the media type. Data in the 
pchBuffer parameter is returned to the application in the standard presentation format. 

With images, for example, the standard data presentation format is uncompressed OS/2 bit-map data. For audio, the standard presentation 
is PCM data. The data will conform to the definition found in the media header supplied by mmioGetFleader. 


mmioRead - Related Functions 


mmioClose 

mmioOpen 

mmioSeek 

mmioWrite 


mmioRead - Example Code 


The following code illustrates how to read from a file. 

HMMIO hmmiol; 

PCHAR pchBuffer; 

LONG cBytes; 

LONG lBytesRead; 


lBytesRead = mmioRead (hmmiol , pchBuffer, cBytes); 

if (lBytesRead < OL) 

/* error */ 
else 
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mmioRemoveElement 


mmioRemoveElement - Syntax 


This function removes a specific element from a compound file. mmioRemoveElement is a 32-bit function that is also provided as a 16-bit 
entry point. 


#def ine 

INCL_MACHDR 


#include 

<os2 . h> 


PSZ 

pszFileElement; 

/* 

ULONG 

ulFlag; 

/* 

ULONG 

rc; 

/* 


Pointer to file element name. */ 
Flags. */ 

Return codes. */ 


rc = mmioRemoveElement (pszFileElement, ulFlag); 


mmioRemoveElement Parameter - pszFileElement 


pszFileElement (PSZ) - input 

Pointer to a compound-file element name in the format: a:\path\file+element. 


mmioRemoveElement Parameter - ulFlag 


ulFlag (ULONG) - input 

Specifies possible options. Contains 0 or the following flag: 

MMIO_RE_COMPACT 

Compacts the compound file after removing the element. If no element is specified but this flag is set, the 
compound file will be compacted. If the element is specified but does not exist, no file compaction is done. 


mmioRemoveElement Return Value - rc 


rc (ULONG) - returns 

Returns MMIO_SUCCESS if there was no error; otherwise it returns an error code. 

MMIOERR_CF_ENTRY_NOT_FOUND 

Element can not be found. 

MMIOERRINVALIDPARAMETER 

No element name specified in the pszF//eE/ement parameter and the MMIO_RE_COMPACT flag is not set. 


mmioRemoveElement - Parameters 


pszFileElement (PSZ) - input 

Pointer to a compound-file element name in the format: a:\path\file+element. 
ulFlag (ULONG) - input 

Specifies possible options. Contains 0 or the following flag: 

MMIO_RE_COMPACT 

Compacts the compound file after removing the element. If no element is specified but this flag is set, the 
compound file will be compacted. If the element is specified but does not exist, no file compaction is done. 


rc (ULONG) - returns 

Returns MMIO_SUCCESS if there was no error; otherwise it returns an error code. 

MMIOERR_CF_ENTRY_NOT_FOUND 

Element can not be found. 

MMIOERRINVALIDPARAMETER 

No element name specified in the pszF//eE/ement parameter and the MMIO_RE_COMPACT flag is not set. 


mmioRemoveElement - Remarks 


The mmioRemoveElement function is a high-level interface to remove an element from a compound file. 


mmioRemoveElement - Related Functions 

• mmioFindElement 


mmioRemoveElement - Example Code 


The following code illustrates how to remove an element from a compound file and compact it after it is removed. 

ULONG ulReturnCode ; 

ulReturnCode=mmioRemoveElement ("test . bnd+element" , MMIO_RE_COMPACT) ; 
if (ulReturnCode) 

. . . error 
. . . success 


mmioRemoveElement - Topics 
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mmioSeek 


mmioSeek - Syntax 


This function seeks within a file that was opened using mmioOpen. 


#def ine INCL_MMIOOS2 
#include <os2.h> 


HMMIO 

hmmio; 

/* 

LONG 

lOffset; 

/* 

LONG 

lOrigin ; 

/* 

LONG 

rc; 

/* 


Open file handle. */ 
Offset in bytes. */ 
Origin of offset. */ 
New file position. */ 


rc = mmioSeek (hmmio, lOffset, lOrigin) ; 


mmioSeek Parameter - hmmio 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


mmioSeek Parameter - lOffset 


lOffset (LONG) - input 


Specifies an offset, in bytes, to move the file position to. 


mmioSeek Parameter - lOrigin 


lOrigin (LONG) - input 

Specifies how the /Offset parameter is interpreted: 

SEEK_SET 

Seek to an absolute (bytes from the beginning of the file) seek position specified in the /Offset parameter. This is 
the default. 

SEEK_CUR 

Seek to a relative (bytes from the current file position) seek position specified in the /Offset parameter. 

SEEK_END 

Seek to /Offset bytes from the end of the file. 

MMIO_SEEK_IFRAME 

Seek to the nearest l-frame based on one of the previous flags. This flag can only be used with digital video only 
data tracks (or files). 


mmioSeek Return Value - rc 


rc (LONG) - returns 

Returns the new file position (in bytes) from the beginning of the file. If an error occurs, MMIO_ERROR is returned. A call to 
mmioGetLastError might return the following error: 

MMIOERR_SEEK_FAILED 

Probable hardware error. 


mmioSeek - Parameters 


hmmio (FIMMIO) - input 

The open file handle returned by mmioOpen. 

lOffset (LONG) - input 

Specifies an offset, in bytes, to move the file position to. 
lOrigin (LONG) - input 

Specifies how the /Offset parameter is interpreted: 

SEEK_SET 

Seek to an absolute (bytes from the beginning of the file) seek position specified in the /Offset parameter. This is 
the default. 

SEEK_CUR 

Seek to a relative (bytes from the current file position) seek position specified in the /Offset parameter. 

SEEK_END 

Seek to /Offset bytes from the end of the file. 


MMIO_SEEK_IFRAME 

Seek to the nearest l-frame based on one of the previous flags. This flag can only be used with digital video only 
data tracks (or files). 


rc (LONG) - returns 

Returns the new file position (in bytes) from the beginning of the file. If an error occurs, MMIO_ERROR is returned. A call to 
mmioGetLastError might return the following error: 

MMIOERR_SEEK_FAILED 

Probable hardware error. 


mmioSeek - Remarks 


Seeking past the end of the file does not result in an error; mmioSeek will return the offset of the new file position. Be careful when seeking 
past the end of the file. To determine where the end of a file is, call mmioSeek with the /Offset parameter equal to 0 and the /Or/g/n 
parameter equal to SEEK_END. 

Note: It is invalid to seek backwards (negative) from the beginning of the file. 

In the case of a user-supplied memory (MEM) file, a SEEK_END will seek from the end of the buffer, which might be different from the 
actual end of the data. 


mmioSeek - Related Functions 


mmioClose 

mmioOpen 

mmioRead 

mmioWrite 


mmioSeek - Example Code 


The following code illustrates how to seek within a file. 

HMMIO hmmiol; 

LONG lOffset; 

LONG lOrigin = OL; 

LONG lFilePosition; 


lOffset = OL; 
lOrigin |= SEEK_END ; 

lFilePosition = mmioSeek (hmmiol , lOffset, lOrigin); 

if (lFilePosition < OL) 

/* error */ 
else 


mmioSeek - Topics 
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mmioSendMessage 


mmioSendMessage - Syntax 


This function sends a message to the I/O procedure associated with a file that was opened with mmioOpen. 


#def ine INCL_MMIOOS2 
#include <os2.h> 


HMMIO 

hmmio; 

/* 

USHORT 

usMsg; 

/* 

LONG 

lParaml ; 

/* 

LONG 

lParam2 ; 

/* 

LONG 

rc; 

/* 


Open file handle. */ 
Message #. */ 

Message information. */ 
Message information. */ 
Return codes. */ 


rc = mmioSendMessage (hmmio, usMsg, lParaml, 
!Param2 ) ; 


mmioSendMessage Parameter - hmmio 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


mmioSendMessage Parameter - usMsg 


usMsg (USHORT) - input 

A message number. See MMIO Messages. 


mmioSendMessage Parameter - lParaml 


IParaml (LONG) - input 

Specifies additional message information. If /Paraml for the particular MMIO message being sent is not a LONG value, cast the 
value into a LONG data type. 


mmioSendMessage Parameter - IParam2 


IParam2 (LONG) - input 

Specifies additional message information. If /Param2 for the particular MMIO message being sent is not a LONG value, cast the 
value into a LONG data type. 


mmioSendMessage Return Value - rc 


rc (LONG) - returns 

The return code is specific to the message sent. This includes both successful and failed returns. 

Regarding message-specific return codes, additional information may be contained in the u/ErrorPet field of the MMIOINFO 
structure. This is accessed by called mmioGetLastError. 

MMIO_ERROR 

The message cannot be routed to an lOProc. The handle might be invalid. 

MMIOERR_UNSUPPORTED_MESSAGE 

The I/O procedure does not support the message. 


mmioSendMessage - Parameters 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 

usMsg (USHORT) - input 

A message number. See MMIO Messages. 

IParaml (LONG) - input 

Specifies additional message information. If /Paraml for the particular MMIO message being sent is not a LONG value, cast the 
value into a LONG data type. 

IParam2 (LONG) - input 

Specifies additional message information. If /Pararr>2 for the particular MMIO message being sent is not a LONG value, cast the 
value into a LONG data type. 

rc (LONG) - returns 

The return code is specific to the message sent. This includes both successful and failed returns. 

Regarding message-specific return codes, additional information may be contained in the u/ErrorPet field of the MMIOINFO 
structure. This is accessed by called mmioGetLastError. 

MMIO_ERROR 

The message cannot be routed to an lOProc. The handle might be invalid. 


MMIOERR_UNSUPPORTED_MESSAGE 

The I/O procedure does not support the message. 


mmioSendMessage - Remarks 


An application can issue mmioSendMessage to send private messages to an installable I/O procedure. This function enables a program to 
call an I/O procedure directly (unlike system messages, which should be sent by the MMIO Manager). MMIOOS2.H in the \TOOLKIT\H 
subdirectory defines the identifier MMIOM_USER so that you can create your own messages. The mmioSendMessage function requires 
that your custom messages be defined between the MMIOM_USER and MMIOM_USER_END values defined in the MMIOOS2.H file. 


mmioSendMessage - Related Functions 

• mmiolnstalllOProc 


mmioSendMessage - Example Code 


The following code illustrates how to send a message to the lOProc. 

HMMIO hmmiol; 

USHORT usMsg; 

LONG lParaml = OL; 

LONG lParam2 = OL; 

LONG rc; 


usMsg = MMIOM_GETCF ; 

rc = mmioSendMessage (hmmiol , usMsg, lParaml, lParam2) ; 

if ( ! rc) 

/* error */ 
else 


mmioSendMessage - Topics 
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mmioSet 


mmioSet - Syntax 


This function can be used to set or query various extended information. It can associate a CODEC with an I/O procedure, set the current 
track for multiple track files, set the playing speed of a digital video, and so forth. 


#def ine INCL_MMIOOS2 
/(include <os2.h> 


HMMIO 

hmmio; 

/* 

Open file handle. */ 

PMMEXTENDINFO 

pUserExtendmminfo; 

/* 

Extended information 

ULONG 

ulFlags; 

/* 

Flags. */ 

ULONG 

rc ; 

/* 

Return codes. */ 


rc = mmioSet (hmmio, pUserExtendmminf o, ulFlags) ; 


mmioSet Parameter - hmmio 


hmmio (HMMIO) - input 

The MMIO file handle returned by mmioOpen. 


mmioSet Parameter - pUserExtendmminfo 


pUserExtendmminfo (PMMEXTENDINFO) - input 
Pointer to the MMEXTENDINFO structure. 


mmioSet Parameter - ulFlags 


ulFlags (ULONG) - input 

This parameter contains one of the following flags: 

Note: To reference a track other than the default track with the QUERY and SET calls, the MMIO_TRACK and 
MMIO_CODEC_ASSOC flags must be set at the same time the QUERY or SET is performed. 

MMIO_SET_EXTENDEDINFO 

Set the extended information. 


MMIO_QUERY_EXTENDEDINFO_BASE 

Query only the information of the MMEXTENDINFO structure. 

MMIO_QUERY_EXTENDEDINFO_ALL 

Query all extended information including the CODEC associated information. 


mmioSet Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 
MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

Invalid MMIO handle was passed. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 


mmioSet - Parameters 


hmmio (FIMMIO) - input 

The MMIO file handle returned by mmioOpen. 

pUserExtendmminfo (PMMEXTENDINFO) - input 
Pointer to the MMEXTENDINFO structure. 

ulFlags (ULONG) - input 

This parameter contains one of the following flags: 

Note: To reference a track other than the default track with the QUERY and SET calls, the MMIO_TRACK and 
MMIO_CODEC_ASSOC flags must be set at the same time the QUERY or SET is performed. 

MMIO_SET_EXTENDEDINFO 

Set the extended information. 

MMIO_QUERY_EXTENDEDINFO_BASE 

Query only the information of the MMEXTENDINFO structure. 

MMIO_QUERY_EXTENDEDINFO_ALL 

Query all extended information including the CODEC associated information. 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 
MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

Invalid MMIO handle was passed. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 


mmioSet - Remarks 


If MMIO_SET_EXTENDEDINFO is set to associate a CODEC procedure with an open file, the pCODEC/n/H/e/nfo field of the 
CODECASSOC structure is used to identify each CODEC procedure installed in the initialization file. As a result of the set, the CODEC 
procedures are opened and each pCodecOpen structure is passed to its corresponding CODEC procedure. 

On query, two levels of information can be returned. If MMIO_QUERY_EXTENDEDINFO_BASE is set, only the MMEXTENDINFO structure 
is returned. The u/NumCODECs is the number of currently associated CODEC procedures. The u/BufS/ze field is the buffer size for the 
second level information. If the application decides to query the second level information, the MMIO_QUERY_EXTENDEDINFO_ALL flag 
must be set and the pUserExtendmm/nfo parameter must point to a buffer with the size equal to the u/BufS/ze field of the 
MMEXTENDINFO structure. 

This function associates a CODEC procedure with an MMIO handle. Typically, this function is used to provide CODEC information for a new 
file being created. When an existing movie file is opened, any necessary CODEC procedures are loaded by the I/O procedure automatically 
based on the compression type and subtype specified in the file's header. Fiowever, there might be a need to change the output format (for 
example, color depth) of a CODEC and this function can be used for that. The default color depth is set to the display mode color depth for 
files opened for reading (that is, playback of a movie file). 

If this function is not issued, no data compression and decompression will be performed for MMIO_READ and MMIO_WRITE. 

Note: for digital video files, all reads and writes are MULTITRACK_READ and MULTITRACK_WRITE.) 


mmioSet - Example Code 


The following code illustrates how to set CODEC information for an opened file. 

HMMIO hmmiol; 

MMEXTENDINFO mmExtendlnf o; 

CODECASSOC codecAssoc; 

CODECINIFILEINFO codecIniFilelnf o; 

ULONG ulFlags; 

ULONG rc; 


hmmiol = mmioOpen ( "MYFILE . SMV" , &mmioInfo, MMIO_CREATE) ; 
mmExtendlnf o . ulStructLen = sizeof (MMEXTENDINFO) ; 
mmExtendlnf o.ulFlags = MMIO_CODEC_ASSOC; 
mmExtendlnf o . ulNumCODECs = 1; 
mmExtendlnf o .pCODECAssoc = &codecAssoc; 

codecIniFilelnf o . ulStructLen = sizeof (CODECINIFILEINFO) ; 
codecIniFilelnf o. fee = FOURCC_MYPROC 

codecIniFilelnf o . ulCompressType = COMPRESSTYPE_MYPROC; 
codecIniFilelnf o.ulCompressSubType = COMPRESSSUBTYPE_MYPROC; 
codecIniFilelnf o . ulMediaType = MEDIATYPE_MYPROC ; 
codecIniFilelnf o . ulCapsFlags = CODEC_DECOMPRESS; 
codecIniFilelnf o . szHWID = HWID_MYPROC; 
codecAssoc .pCODECIniFilelnfo = ScodecIniFilelnf o; 
codecAssoc .pCodecOpen = NULL; 


ulFlags = MMIO_SET_EXTENDEDINFO; 

rc = mmioSet (hmmiol , mmExtendlnf o, ulFlags); 

if (rc) 

/* error */ 
else 
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mmioSetBuffer 


mmioSetBuffer - Syntax 


This function enables or disables buffered I/O, or changes the buffer or buffer size, for a file that was opened using mmioOpen. 


#def ine INCL_MMIOOS2 
/(include <os2.h> 


HMMIO 

hmmio; 

/* 

Open file handle 

PCHAR 

pchBuffer; 

/* 

Pointer. */ 

LONG 

cBytes; 

/* 

Buffer size. */ 

USHORT 

usFlags; 

/* 

Flags. */ 

USHORT 

rc; 

/* 

Return codes. */ 


rc = mmioSetBuffer (hmmio, pchBuffer, cBytes, 
usFlags) ; 


mmioSetBuffer Parameter - hmmio 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


mmioSetBuffer Parameter - pchBuffer 


pchBuffer (PCHAR) - input 

A pointer to the caller-supplied buffer to use for buffered I/O. It can be NULL if the caller wants mmioSetBuffer to allocate the buffer, 
or wants buffered I/O to be disabled. 


mmioSetBuffer Parameter - cBytes 


cBytes (LONG) - input 

The size of the caller-supplied buffer, or (if pchBuffer is NULL) the size of the buffer that the caller wants mmioSetBuffer to allocate. 


mmioSetBuffer Parameter - usFlags 


usFlags (USHORT) - input 

Reserved for future use and must be set to zero. 


mmioSetBuffer Return Value - rc 


rc (USHORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not correct. 

MMIOERRJJNBUFFERED 

Tried to disable a buffer already disabled. 

MMIOERRINVALIDBUFFERLENGTH 

The buffer length is invalid. 

MMIOERR_CANNOTWRITE 

The buffer could not be written to disk. It might be full. 

MMIOERR_READ_FAILED 

Set Buffer failed during a read operation. 

MMIOERR_SEEK_FAILED 

Set Buffer failed during a seek operation. 

MMIOERR_WRITE_FAILED 

Set Buffer failed during a write operation. 

MMIOERR_OUTOFMEMORY 

A buffer was expected but not allocated. 


mmioSetBuffer - Parameters 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


pchBuffer (PCHAR) - input 

A pointer to the caller-supplied buffer to use for buffered I/O. It can be NULL if the caller wants mmioSetBuffer to allocate the buffer, 
or wants buffered I/O to be disabled. 


cBytes (LONG) - input 

The size of the caller-supplied buffer, or (if pchBuffer is NULL) the size of the buffer that the caller wants mmioSetBuffer to allocate. 

usFlags (USHORT) - input 

Reserved for future use and must be set to zero. 

rc (USHORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRINVALIDHANDLE 

The handle passed was not correct. 

MMIOERRJJNBUFFERED 

Tried to disable a buffer already disabled. 

MMIOERRINVALIDBUFFERLENGTH 

The buffer length is invalid. 

MMIOERR_CANNOTWRITE 

The buffer could not be written to disk. It might be full. 

MMIOERR_READ_FAILED 

Set Buffer failed during a read operation. 

MMIOERR_SEEK_FAILED 

Set Buffer failed during a seek operation. 

MMIOERR_WRITE_FAILED 

Set Buffer failed during a write operation. 

MMIOERR_OUTOFMEMORY 

A buffer was expected but not allocated. 


mmioSetBuffer - Remarks 


If the pchBuffer parameter is NULL and the cchBuffer field of MMIOINFO is 0, buffered I/O is disabled. If pchBuffer is NULL and cchBuffer 
is not 0 and buffering was enab/ecf before mmioSetBuffer was called and the I/O buffer was allocated by mmioOpen or a previous call to 
mmioSetBuffer, then mmioSetBuffer reallocates the I/O buffer to be cchBuffer bytes in length. The contents of the buffer are not disturbed in 
this case (though if the buffer is shrunk, some data will be lost), unless the current file position is in part of the buffer that is truncated. 

If pchBuffer is NULL and cchBuffer is not 0 and buffering was cf/sabfecf before mmioSetBuffer was called, then mmioSetBuffer allocates an 
I/O buffer of cchBuffer bytes in length, and buffered I/O is enabled. 

If pchBuffer is not NULL and cchBuffer is not 0, then pchBuffer is assumed to be a caller-provided I/O buffer of cchBuffer bytes in length, 
which is used for buffered I/O. 


mmioSetBuffer - Related Functions 


mmioFlush 


mmioSetBuffer - Example Code 


The following code illustrates how to set the buffer. 


HMMIO hmmiol; 

LONG cchBuffer; 
PCHAR pchBuffer; 
USHORT usFlags = 0; 
USHORT rc; 


pchBuffer = NULL; 
cchBuffer = 0L; 

rc = mmioSetBuf fer (hmmiol , pchBuffer, cchBuffer, usFlags) ; 

if (rc) 

/* error */ 
else 
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mmioSetHeader 


mmioSetHeader - Syntax 


This function sets attributes of the media in a file opened for writing by mmioOpen. It issues an MMIOM_SETFIEADER message to the I/O 
procedure. The specific header depends on the media type of the file and current track setting, in the case of multiple tracks. This header 
can be a raw header or a translated header. 

This function does not change the current file position. Typically, mmioGetFleader is issued to obtain the attribute data and mmioSetFleader 
is issued to update it. mmioSetFleader can be issued independently of mmioGetFleader, such as to create the header initially. 


#def ine INCL_MMIOOS2 
ftinclude <os2.h> 


HMMIO 

hmmio; 

/* 

PVOID 

pHeader; 

/* 

LONG 

lHeaderLength; 

/* 

PLONG 

plBytesWritten; 

/* 

ULONG 

ulReserved; 

/* 

ULONG 

ulFlags; 

/* 


Open file handle. */ 

Pointer to header structure. */ 
Size of header structure. */ 

# of bytes written. */ 

Reserved. */ 

Reserved. */ 


ULONG 


rc; 


/* Return codes. */ 


rc 


mmioSetHeader (hmmio, pHeader, 
plBytesWritten, ulReserved, 


IHeaderLength, 
ulFlags) ; 


mmioSetHeader Parameter - hmmio 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


mmioSetHeader Parameter - pHeader 


pHeader (PVOID) - input 

Pointer to a header structure. This structure contains the data that is written to the header. 

If the MMIO_TRANSLATEHEADER flag was set on the mmioOpen in the u/Trans/ate field of the MMIOINFO structure on the 
mmioOpen function, then the header expected by the call is one associated with the standard presentation format for that particular 
multimedia data type (media type). Each media type (see the u/Med/aType field of the MMFORMATINFO structure.) has a different 
standard presentation header. 

The I/O procedure is expected to transpose the header from this standard format into the native format before writing the header to 
the file. 

If MMIO_NOTRANSLATE was specified on the open (default case) then the header is in its native format. The currently defined 
values for each u/Med/aType and their respective media structures are as follows: 

MMIO_MEDIATYPE_IMAGE 

The data represents a still image. Images use the MMIMAGEHEADER as the media structure. 
MMIO_MEDIATYPE_AUDIO 

The data represents digital audio. Digital-audio data streams use MMAUDIOHEADER as the media structure. 
MMIO_MEDIATYPE_MIDI 

The data represents MIDI streams. MIDI data streams use MMMIDIHEADER as the media structure. 
MMIO_MEDIATYPE_DIGITALVIDEO 

The data represents digital video. Digital video data uses MMVIDEOHEADER as the media structure. 
MMIO_MEDIATYPE_MOVIE 


The data represents a movie. Movie data uses MMMOVIEHEADER as the media structure. 


mmioSetHeader Parameter - IHeaderLength 


IHeaderLength (LONG) - input 

The size of the header structure in bytes. 


mmioSetHeader Parameter - pIBytesWritten 


pIBytesWritten (PLONG) - in/out 

Returns the number of bytes written to the header structure. 


mmioSetHeader Parameter - ulReserved 


ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioSetHeader Parameter - ulFlags 


ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 


mmioSetHeader Return Value - rc 


rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The specified file is not a media-file format type. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERR_SEEK_FAILED 

A seek operation prior to a write- or read-advance operation failed. 


mmioSetHeader - Parameters 


hmmio (HMMIO) - input 


The open file handle returned by mmioOpen. 
pHeader (PVOID) - input 

Pointer to a header structure. This structure contains the data that is written to the header. 

If the MMIO_TRANSLATEHEADER flag was set on the mmioOpen in the u/Trans/ate field of the MMIOINFO structure on the 
mmioOpen function, then the header expected by the call is one associated with the standard presentation format for that particular 
multimedia data type (media type). Each media type (see the u/Med/aType field of the MMFORMATINFO structure.) has a different 
standard presentation header. 

The I/O procedure is expected to transpose the header from this standard format into the native format before writing the header to 
the file. 

If MMIO_NOTRANSLATE was specified on the open (default case) then the header is in its native format. The currently defined 
values for each u/Med/aType and their respective media structures are as follows: 

MMIO_MEDIATYPE_IMAGE 

The data represents a still image. Images use the MMIMAGEFIEADER as the media structure. 
MMIO_MEDIATYPE_AUDIO 

The data represents digital audio. Digital-audio data streams use MMAUDIOFIEADER as the media structure. 
MMIO_MEDIATYPE_MIDI 

The data represents MIDI streams. MIDI data streams use MMMIDIFIEADER as the media structure. 
MMIO_MEDIATYPE_DIGITALVIDEO 

The data represents digital video. Digital video data uses MMVIDEOFIEADER as the media structure. 
MMIO_MEDIATYPE_MOVIE 


The data represents a movie. Movie data uses MMMOVIEFIEADER as the media structure. 

IHeaderLength (LONG) - input 

The size of the header structure in bytes. 

pIBytesWritten (PLONG) - in/out 

Returns the number of bytes written to the header structure. 

ulReserved (ULONG) - input 

Reserved for future use and must be set to zero. 

ulFlags (ULONG) - input 

Reserved for future use and must be set to zero. 

rc (ULONG) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIO_ERROR 

The specified file is not a media-file format type. 

MMIOERRINVALIDPARAMETER 

An invalid parameter was passed. 

MMIOERRINVALIDHANDLE 

The handle passed was not valid. 

MMIOERR_SEEK_FAILED 

A seek operation prior to a write- or read-advance operation failed. 


mmioSetHeader - Remarks 


The contents of the header must represent the structure that is expected by the I/O procedure. It does not represent the manner in which 


the data will be saved by the I/O procedure, because the I/O procedure might translate the data in some manner. The p/Bytes Written 
parameter value might differ from the actual number of bytes written to the file in the case of translations. 

This function can be used in conjunction with mmioSet to set (write) a specific track header into a multiple track movie file. 


mmioSetHeader - Related Functions 


mmioGetHeader 

mmioQueryHeaderLength 


mmioSetFleader - Example Code 


The following code illustrates how to update header attributes. 

HMMIO hmmiol; 

MMAUDIOHEADER mmAudioHeader; 

LONG lBytesWritten; 

ULONG ulReserved = OL; 

ULONG ulFlags = OL; 

ULONG rc; 


memset ( &mmAudioHeader , ' \0 ' , sizeof (MMAUDIOHEADER) ) ; 


rc = mmioSetHeader ( hmmiol, 

(PVOID) &mmAudioHeader , 

(LONG) sizeof (MMAUDIOHEADER) , 
& lBytesWritten, 
ulReserved, 
ulFlags) ; 

if (rc) 

/* error */ 
else 
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mmioSetlnfo 


mmioSetlnfo - Syntax 


This function updates information on a file I/O buffer of a file opened for buffered I/O. 


#def ine INCL_MMIOOS2 
/(include <os2.h> 


HMMIO 

hmmio; 

/* 

Open file handle 

PMMIOINFO 

pmmioinfo; 

/* 

Buffer. */ 

USHORT 

usFlags; 

/* 

Reserved. */ 

USHORT 

rc; 

/* 

Return codes. */ 


rc = mmioSetlnfo (hmmio, pmmioinfo, usFlags) ; 


mmioSetlnfo Parameter - hmmio 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


mmioSetlnfo Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) - input 

The caller-allocated MMIOINFO buffer that was filled with information by mmioGetlnfo. 


mmioSetlnfo Parameter - usFlags 


usFlags (USHORT) - input 

Reserved for future use and must be set to zero. 


mmioSetlnfo Return Value - rc 


rc (USHORT) - returns 

Return codes indicating success or type of failure: 


MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRJJNBUFFERED 

Tried to disable a buffer that was already disabled. 

MMIOERR INVALID HANDLE 

The handle passed was not correct. 

MMIOERR INVALID PARAMETER 

An incorrect parameter was passed. 


mmioSetlnfo - Parameters 


hmmio (FIMMIO) - input 

The open file handle returned by mmioOpen. 

pmmioinfo (PMMIOINFO) - input 

The caller-allocated MMIOINFO buffer that was filled with information by mmioGetlnfo. 

usFlags (USPIORT) - input 

Reserved for future use and must be set to zero. 

rc (USPIORT) - returns 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

If the function succeeds, 0 is returned. 

MMIOERRJJNBUFFERED 

Tried to disable a buffer that was already disabled. 

MMIOERR INVALID HANDLE 

The handle passed was not correct. 

MMIOERR INVALID PARAMETER 

An incorrect parameter was passed. 


mmioSetlnfo - Remarks 


If using buffered I/O, make sure you set the MMIO_DIRTY flag in the u/F/ags field of MMIOINFO (before calling mmioSetlnfo), if you have 
written to the buffer. Otherwise, the contents of the buffer will not be written to disk. 


mmioSetlnfo - Related Functions 


mmioAdvance 

mmioGetlnfo 


mmioSetlnfo - Example Code 


The following code illustrates how to update open file information. 

HMMIO hmmiol; 

MMIOINFO mmioinfo; 

USHORT usFlags = 0; 

USHORT rc; 


memset ( &mmioinfo, ' \0', sizeof (MMIOINFO) ); 
rc = mmioGetlnfo ( hmmiol, &mmioinfo, usFlags) ; 
if (rc) 

/* error */ 
else 

/* do some low-level I/O */ 


rc = mmioSetlnfo ( hmmiol, &mmioinfo, usFlags); 

if (rc) 

/* error */ 
else 
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mmioStringToFOURCC 


mmioStringToFOURCC - Syntax 


This function converts a null-terminated string to a four-character code (FOURCC). 


#def ine INCL_MMIOOS2 
#include <os2.h> 


PSZ 

pszString; 

/* 

String 

to convert. */ 

USHORT 

usFlags; 

/* 

Flags . 

*/ 

FOURCC 

rc; 

/* 

Return 

codes. */ 


rc = mmioStringToFOURCC (pszString, usFlags); 


mmioStringToFOURCC Parameter - pszString 


pszString (PSZ) - input 

The string to convert to a FOURCC. 


mmioStringToFOURCC Parameter - usFlags 


usFlags (USFIORT) - input 

Contains 0 or the following flag: 

MMIO_TOUPPER 

All the characters in the four-character code are converted to uppercase. 


mmioStringToFOURCC Return Value - rc 


rc (FOURCC) - returns 

Returns the four-character code. 


mmioStringToFOURCC - Parameters 


pszString (PSZ) - input 

The string to convert to a FOURCC. 


usFlags (USFIORT) - input 

Contains 0 or the following flag: 


MMIO_TOUPPER 

All the characters in the four-character code are converted to uppercase. 


rc (FOURCC) - returns 

Returns the four-character code. 


mmioStringToFOURCC - Remarks 


This function does not check to see if the pszString parameter follows any conventions regarding which characters to include in a FOURCC 
code. The string is simply copied to a FOURCC code, and padded with blanks to the right or truncated to four characters, as required. 


mmioStringToFOURCC - Related Functions 


mmioAscend 

mmioCreateChunk 

mmioDescend 

mmioFOURCC 


mmioStringToFOURCC - Example Code 


The following code illustrates how to convert a string to a four-character code. 

FOURCC fee; 

fee = mmioStringToFOURCC ( "IMG", MMIO_TOUPPER ); 

if ( ! fee) 

/* error */ 
else 


mmioStringToFOURCC - Topics 
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mmioWrite 


mmioWrite - Syntax 


This function writes to a file that was opened using mmioOpen. 


#def ine INCL_MMIOOS2 
#include <os2.h> 


HMMIO 

hmmio; 

/* 

Open file 

handle. */ 

PCHAR 

pchBuffer; 

/* 

Buffer to 

write from. */ 

LONG 

cBytes; 

/* 

Number of 

bytes. */ 

LONG 

rc; 

/* 

Number of 

bytes actually written. */ 


rc = mmioWrite (hmmio, pchBuffer, cBytes) ; 


mmioWrite Parameter - hmmio 


hmmio (HMMIO) - input 

The open file handle returned by mmioOpen. 


mmioWrite Parameter - pchBuffer 


pchBuffer (PCHAR) - input 

The buffer to write from. 


mmioWrite Parameter - cBytes 


cBytes (LONG) - input 

The number of bytes to write from the pchBuffer parameter buffer to the file. 


mmioWrite Return Value - rc 


rc (LONG) - returns 

Returns the number of bytes actually written. If an error occurs, MMIO_ERROR is returned. A call to mmioGetLastError might return 
one of the following errors: 

MMIOERR_READ_ONLY_FILE 

File not opened in WRITE mode. 

MMIOERRINVALIDHANDLE 

Invalid handle specified. 

MMIOERR_WRITE_FAILED 

Unable to write; probable hardware error. 

MMIOERR_SEEK_FAILED 

Unable to seek; probable hardware error. 

MMIOERR_READ_FAILED 

Unable to read; probable hardware error. 


MMIOERRINVALIDBUFFERLENGTH 

The buffer length is invalid. 

MMIOERR_NO_BUFFER_ALLOCATED 

A buffer was expected but none was found. 

MMIOERR_CANNOTWRITE 

The target media has no space available. 


mmioWrite - Parameters 


hmmio (FIMMIO) - input 

The open file handle returned by mmioOpen. 

pchBuffer (PCFIAR) - input 

The buffer to write from. 

cBytes (LONG) - input 

The number of bytes to write from the pchBuffer parameter buffer to the file, 
rc (LONG) - returns 

Returns the number of bytes actually written. If an error occurs, MMIO_ERROR is returned. A call to mmioGetLastError might return 

one of the following errors: 

MMIOERR_READ_ONLY_FILE 

File not opened in WRITE mode. 

MMIOERRINVALIDHANDLE 

Invalid handle specified. 

MMIOERR_WRITE_FAILED 

Unable to write; probable hardware error. 

MMIOERR_SEEK_FAILED 

Unable to seek; probable hardware error. 

MMIOERR_READ_FAILED 

Unable to read; probable hardware error. 

MMIOERRINVALIDBUFFERLENGTFI 

The buffer length is invalid. 

MMIOERR_NO_BUFFER_ALLOCATED 

A buffer was expected but none was found. 

MMIOERR_CANNOTWRITE 

The target media has no space available. 


mmioWrite - Remarks 


For a memory file (MEM) that cannot expand, mmioWrite returns the number of bytes written. This might be fewer than requested if the end 
of file (EOF) was encountered prematurely. If the logical file pointer was past the EOF when the write operation was initiated, 
MMIO_ERROR is returned. If a pointer is at the EOF, a 0 is returned indicating no bytes were written. If the file can expand, it will do so and 
write the number of bytes requested, even if the logical file pointer was past the EOF when the write operation was initiated. 

Note: User buffers cannot be expanded, but system-allocated buffers can be expanded. 


Elements of a compound file will behave similar to the way a memory file does. The key to whether an element can be expanded is if the 
element is opened with the MMIO_APPEND flag set. 

If the MMIO_TRANSLATEDATA flag was sent when the file was opened, the data is expected in the standard presentation format for the 
specific media type. The I/O procedure will translate the data from the standard presentation format into the I/O procedure format-specific 
representation before writing to the file. With images, for example, the standard data presentation format in uncompressed OS/2 2.0 bit-map 
data. For audio, the standard representation is uncompressed PCM data. The data will conform to the definition found in the media header 
supplied by mmioSetHeader. 


mmioWrite - Related Functions 


• mmioClose 

• mmioGetLastError 

• mmioOpen 

• mmioFtead 

• mmioSeek 


mmioWrite - Example Code 


The following code illustrates how to write to a file. 

HMMIO hmmiol; 

PCHAR pchBuffer; 

LONG cBytes; 

LONG lBytesWritten; 


lBytesWritten = mmioWrite (hmmiol , pchBuffer, cBytes); 

if (lBytesWritten < 0L) 

/* error */ 
else 
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MMIO Messages 


The MMIO messages are sent to an I/O procedure as a result of an MMIO function call. For example, when an application calls mmioOpen, 


the MMIOM_OPEN message is sent to an I/O procedure. An application can also send the MMIO messages to an I/O procedure by issuing 
mmioSendMessage or by directly calling the I/O procedure. 


The mmioSendMessage function should be used only to pass user-defined messages, or messages not automatically generated by an 
MMIO function, to the I/O procedure of the user's application. 

When an application issues mmioSendMessage, it passes an hmm/o parameter, which MMIO converts to an MMIOINFO block before 
sending the parameter to the I/O procedure. When an application calls an I/O procedure directly, a pmmioinfo parameter is passed to the 
I/O procedure instead of an hmm/o. The following is a function prototype for a direct I/O procedure call: 


LONG API ENTRY MMIOPROC 

(PVOID pmmioinfo, USHORT usMsg, 
LONG lParaml , LONG !Param2); 


Message 

Description 

MMIOM_BEGIN INSERT 

Requests that all subsequent 
Writes insert data at the current 
seek position. 

MMIOM_BEGINRECORD 

Requests all subsequent Writes be 
considered one logical unit by an 
UNDO or REDO. 

MMIOM_BEGINSTREAM 

Sent before the first mmioRead or 
mmioWrite to start the stream at 
the optimum rate for the file. 

MMIOM_CLEAR 

Requests that a specified range be 
deleted from a file. 

MMIOM_CLOSE 

Requests that the file be closed. 

MM I OM_C OP Y 

Requests that a specified range be 
copied to the clipboard. 

MMIOM_CUT 

Requests that a specified range be 
copied to the clipboard and then 
deleted. 

MMIOM_END STREAM 

Sent after the last mmioRead or 
mmioWrite to end the stream. 

MMIOM_DELETE 

Requests that information be 
removed from a file. 

MMIOM_END INSERT 

Requests that all subsequent 
Writes overwrite data at the 
current seek position. 

MMIOM_ENDRECORD 

Indicates that the logical record 
operation has ended and data 
structures should be updated, if 
necessary . 

MMIOM_GETCF 

Obtains the handle ( hmmcf ) of the 
RIFF compound file. 

MMIOM_GETCFENTRY 

Requests a CTOC entry for an 
element of a RIFF compound file. 

MMIOM_GETFORMATINFO 

Requests that the IOProc return an 
MMFORMATINFO structure. 

MM I OM_GE TF ORMATN AME 

Requests the format name for the 
IOProc . 

MMIOM_GETHEADER 

Requests that the IOProc return 
media-specific information. 

MMIOM_IDENTIFYFILE 

Attempts to determine if any 
IOProc can process a file. 

MMI OM_MULT I TRACKREAD 

Requests that data be read from a 
movie file. 


MM I OM_MULT I TRACKWRI TE 

Requests that data be written to a 
movie file. 

MMIOM_OPEN 

Requests that a file be opened or 
deleted. 

MMIOM_PASTE 

Requests that data from the 
clipboard be inserted into a file. 

MMI OM_QUERYHEADERLENGTH 

Requests that the IOProc return 
the size the header. 

MMI OM_QUERY IMAGE 

Requests that the IOProc return 
the currently selected image index 
in the image file. 

MMIOM_QUERYIMAGECOUNT 

Requests that the IOProc return 
the number of images stored in the 
image file. 

MMIOM_READ 

Requests that bytes be read from 
an open file. 

MMIOM_REDO 

Requests that the last logical 
action which was undone be redone. 

MM I OM_S AVE 

Requests temporary changes in a 
file . 

MMIOM_SEEK 

Requests that the current file 
position be moved. 

MMIOM_SEEKBYTIME 

Requests that the file position be 
moved relative to some unit of 
time . 

MMIOM_SET 

Requests that extended file 
information be set or queried. 

MMIOM_SETHEADER 

Requests that the IOProc use 
media-specific information when 
writing or accepting data. 

MMI OM_SET IMAGE 

Selects a new image index in the 
image file. 

MMIOM_STATUS 

Used to pass appropriate 
MCI_STATUS requests to an IOProc. 

MMIOM_TEMPCHANGE 

Requests that all subsequent 
Writes to the media be treated as 
temporary changes . 

MMIOM_UNDO 

Requests that the last logical 
action, either a delete, insert, 
undo, or redo, be undone. 

MMIOM_WINMSG 

Allows an application or an MCD to 
pass PM messages from a window 
procedure to an IOProc. 

MMIOM_WRITE 

Requests that the bytes be written 
to an open file. 


The MMIO messages indicate, to the I/O procedure, the type of MMIO operation to be performed. I/O procedures can be called to process 
files that might or might not use the RIFF format standard. 

Note: The compound-file messages must not be used while creating or appending to the compound file itself. 


MMIOM BEGININSERT 


MMIOMBEGININSERT Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM BEGININSERT Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_BEGININSERT. 


MMIOM BEGININSERT Parameter - IParaml 


IParaml (LONG) 

This parameter is not used. 


MMIOM BEGININSERT Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM BEGININSERT Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The file is in insert mode. 

MMIO_ERROR 

An error code is returned. 


MMIOM_BEGININSERT- Description 


This message is sent to an I/O procedure to request that all subsequent mmioWrite calls insert data at the current seek position rather than 
overwriting the data. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_BEGININSERT. 

IParaml (LONG) 

This parameter is not used. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The file is in insert mode. 

MMIO_ERROR 

An error code is returned. 
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MMIOM BEGINRECORD 


MMIOMBEGINRECORD Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM BEGINRECORD Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_BEGINRECORD. 


MMIOMBEGINRECORD Parameter - IParaml 

IParaml (LONG) 

This parameter is not used. 


MMIOM BEGINRECORD Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM BEGINRECORD Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 


MMIOM BEGINRECORD - Description 

This message is sent to an I/O procedure to request that all subsequent mmioWrite be considered one logical unit by an MMIOMJJNDO or 
MMIOM_REDO message. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_ESEGINRECORD. 

IParaml (LONG) 

This parameter is not used. 


IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 
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MMIOM BEGINSTREAM 


MMIOMBEGINSTREAM Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM BEGINSTREAM Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_BEGINSTREAM. 


MMIOM BEGINSTREAM Parameter - IParaml 


IParaml (LONG) 

Contains one of the following values: 


STREAM_READ 


Read stream from server to client. 


STREAMJA/RITE 

Write stream from client to server. 


MMIOMBEGINSTREAM Parameter - pParam2 


pParam2 (PQOSInfo) 

A pointer to a QOSInfo structure. This structure contains a variable length array of QOS structures. Each QOS structure contains one 
quality of service parameter (specified in the /QOSParm/c/ field of the QOS structure) which is of one of the following: 

SERVICE_REQUEST 

This requests the type of service required for this stream. The /QOSVa/ue field of the QOS structure contains the 
type of service: GUARANTEED, DONTCARE, or DONTRESERVE. 

MAX_EE_JITTER 

The number of stream buffers for handling jitter. Buffers needed to store a single unit of data are separate. The 
/QOSVa/ue field of the QOS structure contains the number of buffers. 

MAX_DATA_RATE 

Maximum data rate in bytes per second. The /QOSVa/ue field of the QOS structure contains this information. 
AVG_DATA_RATE 

Average data rate in bytes per second. The /QOSVa/ue field of the QOS structure contains this information. 


MMIOM BEGINSTREAM Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The file is in streaming mode. 

MMIOERR_UNSUPPORTED_MESSAGE 

lOProc does not support this message. 

MMIOERR_QOSUNAVAILABLE 

Quality of service is unavailable. 

MMIO_ERROR 

Streaming was unsuccessful due to other errors. 


MMIOM BEGINSTREAM - Description 


This message is sent before first mmioRead or mmioWrite streamed at optimum rate to the file. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


usMsg (USHORT) 

Set to MMIOM_BEGINSTREAM. 

IParaml (LONG) 

Contains one of the following values: 

STREAM_READ 

Read stream from server to client. 

STREAM_WRITE 

Write stream from client to server. 

pParam2 (PQOSInfo) 

A pointer to a QOSInfo structure. This structure contains a variable length array of QOS structures. Each QOS structure contains one 
quality of service parameter (specified in the /QOSParm/d field of the QOS structure) which is of one of the following: 

SERVICE_REQUEST 

This requests the type of service required for this stream. The /QOSVa/ue field of the QOS structure contains the 
type of service: GUARANTEED, DONTCARE, or DONTRESERVE. 

MAX_EE_JITTER 

The number of stream buffers for handling jitter. Buffers needed to store a single unit of data are separate. The 
/QOSVa/ue field of the QOS structure contains the number of buffers. 

MAX_DATA_RATE 

Maximum data rate in bytes per second. The /QOSVa/ue field of the QOS structure contains this information. 
AVG_DATA_RATE 

Average data rate in bytes per second. The /QOSVa/ue field of the QOS structure contains this information. 

rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The file is in streaming mode. 

MMIOERR_UNSUPPORTED_MESSAGE 

lOProc does not support this message. 

MMIOERR_QOSUNAVAILABLE 

Quality of service is unavailable. 

MMIO_ERROR 

Streaming was unsuccessful due to other errors. 


MMIOM BEGINSTREAM - Remarks 


Some of the quality of service parameters are required on each call, if one of these is missing, an MMIOERR_UNSUPPORTED_MESSAGE 
error is generated. 

The QOS parameters are kept as a list to allow future addition of quality parameters. "Quality of service" is being explored by the research 
community. With newer applications, changes to QOS parameters may be required. For each of the QOS parameters, the /QOSVa/ue is 
one of the following values: 

GUARANTEED 

The application requests guaranteed service and if requested QOS is unavailable, the connection is not made. 

DONTCARE 

The applications requests the given QOS, but if it is unavailable, a connection may be made without quality of service reservation. 
DONTRESERVE 

The application does not want guarantees, (same as no message). The remaining fields are meaningless and not examined. 


MMIOM BEGINSTREAM - Topics 
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MMIOM CLEAR 


MMIOMCLEAR Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM CLEAR Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_CLEAR. 


MMIOM CLEAR Parameter - IParaml 


IParaml (LONG) 

A pointer to an MMIO_EDIT_PARMS structure. 


MMIOM CLEAR Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM CLEAR Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 


MMIOM CLEAR - Description 


This message is sent to an I/O procedure to request that a specified range be deleted from a file. The clipboard is not used for this 
operation. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_CLEAR. 

IParaml (LONG) 

A pointer to an MMIO_EDIT_PARMS structure. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 


MMIOM CLEAR - Remarks 


The media position will be at the position corresponding to the u/StartT/me field of the MMIO_EDIT_PARMS structure. 
The u/Durat/on field cannot be zero. 
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MMIOM CLOSE 


MMIOMCLOSE Parameter ■ 

■ pmmioinfo 

pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 



MMIOMCLOSE Parameter ■ 

■ usMsg 

usMsg (USHORT) 

Set to MMIOM_CLOSE. 



MMIOM CLOSE Parameter ■ 

■ IParaml 

IParaml (LONG) 

The usF/ags parameter of mmioClose. 



MMIOM CLOSE Parameter ■ 

■ IParam2 

IParam2 (LONG) 

This parameter is not used. 



MMIOM CLOSE Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The specified file was closed successfully. 

MMIO_ERROR 

An error code is returned. 

MMICM/VARNING 

The file was closed, but the lOProc expected additional data. 


MMIOM CLOSE - Description 


This message is sent to an lOProc by mmioClose to request that a file be closed. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_CLOSE. 

IParaml (LONG) 

The usF/ags parameter of mmioClose. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The specified file was closed successfully. 

MMIO_ERROR 

An error code is returned. 

MMIO_WARNING 

The file was closed, but the lOProc expected additional data. 


MMIOM_CLOSE- Topics 
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MMIOM COMPRESS 


MMIOM_COMPRESS Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOMCOMPRESS Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_COMPRESS. 


MMIOM COMPRESS Parameter - IParaml 


IParaml (LONG) 

Pointer to the MMCOMPRESS structure. 


MMIOM COMPRESS Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM COMPRESS Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The data is decompressed successfully. 

MMIO_ERROR 

An error code is returned. 


MMIOM COMPRESS - Description 


This message is sent to an I/O procedure to compress the uncompressed data in the buffer. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_COMPRESS. 

IParaml (LONG) 

Pointer to the MMCOMPRESS structure. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The data is decompressed successfully. 

MMIO_ERROR 

An error code is returned. 


MMIOM COMPRESS - Topics 

Select an item: 

Description 

Returns 

Glossary 


MMIOM COPY 


MMIOMCOPY Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOMCOPY Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_COPY. 


MMIOM COPY Parameter - IParaml 


IParaml (LONG) 

A pointer to an MMIO_EDIT_PARMS structure. 


MMIOM COPY Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM COPY Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 


MMIOM COPY - Description 


This message is sent to an I/O procedure to request that a specified range be copied to the clipboard. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


usMsg (USHORT) 

Set to MMIOM_COPY. 


IParaml (LONG) 

A pointer to an MMIO_EDIT_PARMS structure. 

IParam2 (LONG) 

This parameter is not used. 


rc (ULONG) 


Return codes indicating success or failure: 


MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 


MMIOM COPY -Remarks 


If data is already in the clipboard, it is overwritten with this message call. The media position is not changed by this operation. 
The u/Duration field of the MMIO_EDIT_PARMS structure passed in the /Paraml parameter cannot be set to 0. 


MMIOM_COPY- Topics 
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MMIOM CUT 


MMIOM_CUT Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM_CUT Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_CUT. 


MMIOM CUT Parameter - IParaml 


IParaml (LONG) 

A pointer to an MMIO_EDIT_PARMS structure. 


MMIOM CUT Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM CUT Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 


MMIOM_CUT - Description 


This message is sent to an I/O procedure to request the specified range is copied to the clipboard and then deleted. It performs as if an 
MMIOM_COPY operation immediately followed by a MMIOM_CUT operation were requested. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_CUT. 

IParaml (LONG) 

A pointer to an MMIO_EDIT_PARMS structure. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The request was successful. 


MMIO_ERROR 


An error code is returned. 


MMIOM CUT -Remarks 


If data is already in the clipboard, it is overwritten with this message call. The media position will be at the position corresponding to the 
u/StartT/me field of the MMIO_EDIT_PARMS structure passed in the /Paraml parameter. 

The u/Durat/on field of the MMIO_EDIT_PARMS structure cannot be set to 0. 


MMIOM_CUT- Topics 
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MMIOM DECOMPRESS 


MMIOMDECOMPRESS Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to the MMIOINFO data structure. 


MMIOM DECOMPRESS Parameter - usMsg 


usMsg (USHORT) 

Set to MM IOM_DECOM PRESS. 


MMIOM DECOMPRESS Parameter - IParaml 


IParaml (LONG) 

Pointer to the MMDECOMPRESS structure. 


MMIOM DECOMPRESS Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM DECOMPRESS Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The data is decompressed successfully. 

MMIO_ERROR 

An error code is returned. 


MMIOMDECOMPRESS - Description 


This message is sent to the lOProc to decompress the compressed data in the buffer. 


pmmioinfo (PMMIOINFO) 

A pointer to the MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_DECOM PRESS. 

IParaml (LONG) 

Pointer to the MMDECOMPRESS structure. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The data is decompressed successfully. 

MMIO_ERROR 

An error code is returned. 


MMIOM DECOMPRESS - Topics 


Select an item: 


Description 

Returns 

Glossary 


MMIOM DELETE 


MMIOMDELETE Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM DELETE Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_DELETE. 


MMIOM DELETE Parameter - IParaml 


IParaml (LONG) 

Starting position for deletions. 


MMIOM DELETE Parameter - IParam2 


IParam2 (LONG) 

Length of information to be deleted. 


MMIOM DELETE Return Value - rc 


rc (ULONG) 


Return codes indicating success or failure: 

MMIO_SUCCESS 

The information was removed from the file sucessfully. 

MMIO_ERROR 

An error code is returned. 


MMIOM DELETE - Description 


This message is sent to an I/O procedure to request that information be removed from the file. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_DELETE. 

IParaml (LONG) 

Starting position for deletions. 

IParam2 (LONG) 

Length of information to be deleted, 
rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The information was removed from the file sucessfully. 

MMIO_ERROR 

An error code is returned. 


MMIOM_DELETE- Topics 


Select an item: 
Description 
Returns 
Glossary 


MMIOM ENDINSERT 


MM 10 MEND INSERT Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MM 10 M_END INSERT Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_ENDINSERT. 


MMIOM ENDINSERT Parameter - IParaml 


IParaml (LONG) 

This parameter is not used. 


MMIOM ENDINSERT Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM ENDINSERT Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The file is in overwrite mode. 

MMIO_ERROR 

An error code is returned. 


MMIOM ENDINSERT - Description 


This message is sent to an I/O procedure to request that all subsequent mmioWrite calls overwrite data at the current seek position rather 
than inserting the data. This is the default mode of operation for an I/O procedure. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_ENDINSERT. 

IParaml (LONG) 

This parameter is not used. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The file is in overwrite mode. 

MMIO_ERROR 

An error code is returned. 


MMIOM ENDINSERT - Topics 

Select an item: 

Description 

Returns 

Glossary 


MMIOM ENDRECORD 


MMIOMENDRECORD Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM ENDRECORD Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_ENDRECORD. 


MMIOM ENDRECORD Parameter - IParaml 


IParaml (LONG) 

This parameter is not used. 


MMIOM ENDRECORD Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM ENDRECORD Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The request to the lOProc was successful. 

MMIO_ERROR 

An error code is returned. 


MMIOM ENDRECORD - Description 


This message is sent to an I/O procedure to indicate that the logical record operation has ended and internal I/O procedure data structures 
should be updated if necessary. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_ENDRECORD. 

IParaml (LONG) 

This parameter is not used. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 


The request to the lOProc was successful. 


MMIO_ERROR 

An error code is returned. 


MMIOM ENDRECORD - Topics 

Select an item: 

Description 

Returns 

Glossary 


MMIOM ENDSTREAM 


MMIOMENDSTREAM Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM ENDSTREAM Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_ENDSTREAM. 


MMIOM ENDSTREAM Parameter - IParaml 


IParaml (LONG) 

This parameter is not used. 


MMIOM ENDSTREAM Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM ENDSTREAM Return Value - 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The file is in streaming mode. 

MMIO_UNSUPPORTED_MESSAGE 

I/O procedure does not support this message. 

MMIO_ERROR 

Streaming was unsuccessful due to other errors. 


MMIOMENDSTREAM - Description 


This message deactivates the quality of service for network I/O. 


pmmlolnfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_ENDSTREAM. 

IParaml (LONG) 

This parameter is not used. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The file is in streaming mode. 

MMIO_UNSUPPORTED_MESSAGE 

I/O procedure does not support this message. 

MMIO_ERROR 

Streaming was unsuccessful due to other errors. 


MMIOM ENDSTREAM - Topics 


Select an item: 
Description 


Returns 

Glossary 


MMIOM GETCF 


MMIOM_GETCF Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM GETCF Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_GETCF. 


MMIOM GETCF Parameter - IParaml 


IParaml (LONG) 

This parameter is not used. 


MMIOM GETCF Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM GETCF Return Value - rc 


rc (ULONG) 


Returns a handle (type HMMCF) to the CTOC table that contains the element associated with hmm/o. 
On error, NULL is returned. 


MMIOM GETCF - Description 


This message can be sent by an application to request the return of a handle hmmcfXo the RIFF compound file that contains the element 
associated with hmm/o . 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_GETCF. 

IParaml (LONG) 

This parameter is not used. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 


Returns a handle (type FIMMCF) to the CTOC table that contains the element associated with hmm/o. 
On error, NULL is returned. 


MMIOM_GETCF- Topics 


Select an item: 
Description 
Returns 
Glossary 


MMIOM GETCFENTRY 


MMIOMGETCFENTRY Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOMGETCFENTRY Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_GETCFENTRY. 


MMIOM GETCFENTRY Parameter - IParaml 


IParaml (LONG) 

A pointer to a user buffer (MMCTOCENTRY) that the CTOC entry will be read to. The user needs to allocate a large enough buffer to 
allow for the variable length name field and a possible extra entry field. 


MMIOM GETCFENTRY Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM GETCFENTRY Return Value - rc 


rc (ULONG) 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

User buffer is updated with CTOC entry. 

MMIO_CF_FAILURE 

Error occurred; user buffer was not updated. 


MMIOM GETCFENTRY - Description 

This message can be sent by an application to request a CTOC entry for an element. The element is associated with hmm/o. 


pmmioinfo (PMMIOINFO) 


A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_GETCFENTRY. 

IParaml (LONG) 

A pointer to a user buffer (MMCTOCENTRY) that the CTOC entry will be read to. The user needs to allocate a large enough buffer to 
allow for the variable length name field and a possible extra entry field. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

User buffer is updated with CTOC entry. 

MMIO_CF_FAILURE 

Error occurred; user buffer was not updated. 


MMIOM GETCFENTRY - Topics 

Select an item: 

Description 

Returns 

Glossary 


MMIOM GETFORMATINFO 


MMIOMGETFORMATINFO Parameter - ulReserved 

ulReserved (ULONG) 

Not used. No MMIOINFO block used is required for this message. 


MMIOM GETFORMATINFO Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_GETFORMATINFO. 


MMIOM GETFORMATINFO Parameter - IParaml 


IParaml (LONG) 

A pointer to an MMFORMATINFO structure. The FOURCC, media type, and related information will be written into this structure by 
the lOProc. 


MMIOM GETFORMATINFO Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM GETFORMATINFO Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The specified process installed successfully. 

MMIO_ERROR 

The installation process failed; an error code is returned. 


MMIOM GETFORMATINFO - Description 


This message requests the lOProc to return an MMFORMATINFO structure containing the FOURCC of the format, the capabilities of the 
lOProc, and other information. This message is used to initialize MMFORMATINFO structures internally maintained by the MMIO Manager 
and is issued by MMIO when installing lOProcs. This message does not require that any file be opened or referenced. 


ulReserved (ULONG) 

Not used. No MMIOINFO block used is required for this message. 

usMsg (USHORT) 

Set to MMIOM_GETFORMATINFO. 

IParaml (LONG) 

A pointer to an MMFORMATINFO structure. The FOURCC, media type, and related information will be written into this structure by 
the lOProc. 


IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 


The specified process installed successfully. 


MMIO_ERROR 

The installation process failed; an error code is returned. 


MMIOM GETFORMATINFO - Topics 

Select an item: 

Description 

Returns 

Glossary 


MMIOM GETFORMATNAME 


MMIOM GETFORMATNAME Parameter - ulReserved 


ulReserved (ULONG) 

Not used. No MMIOINFO block is required for this message. 


MMIOM GETFORMATNAME Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_GETFORMATNAME. 


MMIOM GETFORMATNAME Parameter - IParaml 


IParaml (LONG) 

A pointer to a PSZ buffer that contains the format name to be returned. 


MMIOM GETFORMATNAME Parameter - IParam2 


IParam2 (LONG) 


The expected size of the format name. The buffer passed in /Paraml must accommodate this size. If the format name is larger than 
the specified size, it is truncated to /Param2 bytes. 


MMIOM GETFORMATNAME Return Value - rc 


rc (ULONG) 


Upon successful completion, the number of bytes read into the buffer (size of format name) is returned. 
For a failure, 0 is returned. 


MMIOMGETFORMATNAME - Description 


This message requests the format name from the lOProc and will be used by MMIO when processing mmioGetFormatName. This message 
does not require that any file be opened or referenced. 


ulReserved (ULONG) 

Not used. No MMIOINFO block is required for this message. 

usMsg (USHORT) 

Set to MMIOM_GETFORMATNAME. 

IParaml (LONG) 

A pointer to a PSZ buffer that contains the format name to be returned. 

IParam2 (LONG) 

The expected size of the format name. The buffer passed in /Paraml must accommodate this size. If the format name is larger than 
the specified size, it is truncated to /Param2 bytes. 

rc (ULONG) 


Upon successful completion, the number of bytes read into the buffer (size of format name) is returned. 
For a failure, 0 is returned. 


MMIOM GETFORMATNAME - Topics 

Select an item: 

Description 

Returns 

Glossary 


MMIOM GETHEADER 


MMIOMGETHEADER Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM GETHEADER Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_GETHEADER. 


MMIOM GETHEADER Parameter - IParaml 


IParaml (LONG) 

Pointer to a file-specific header structure that will contain information provided by the lOProc. 


MMIOM GETHEADER Parameter - IParam2 


IParam2 (LONG) 

Length in bytes of the structure supplied in /Paraml . 


MMIOM GETHEADER Return Value - rc 


rc (ULONG) 


Upon successful completion, the number of bytes copied to the header structure. 

For a failure, 0 is returned. 

If the length passed in was not enough to hold the header, MMIOERR_INVALID_BUFFER_LENGTFI is set in u/ErrorPet. 
If the header is bad, MMIOERR INVALID STRUCTURE is set in u/ErrorRet. 


MMIOMGETHEADER - Description 


This message requests the lOProc to return media-specific information about the current file or file element. This would include such data as 
resolution and colors for images, and duration and sample rate for audio. Header translation is expected to be performed when specified. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_GETHEADER. 

IParaml (LONG) 

Pointer to a file-specific header structure that will contain information provided by the lOProc. 

IParam2 (LONG) 

Length in bytes of the structure supplied in /Param/ . 
rc (ULONG) 


Upon successful completion, the number of bytes copied to the header structure. 

For a failure, 0 is returned. 

If the length passed in was not enough to hold the header, MMIOERR_INVALID_BUFFER_LENGTH is set in u/ErrorPet. 
If the header is bad, MMIOERR INVALID STRUCTURE is set in u/ErrorRet. 


MMIOM GETHEADER - Remarks 


This message requires that a valid hmm/o handle be returned from a successful call to MMIOM_OPEN 

See mmioGetHeader for more information about header information. 

Examples of some header structures that /Paraml might point to are: 

■ MMIMAGEHEADER (includes structure length, content, size, color type, and other information, including space for a 256-color 
palette) 

• MMAUDIOHEADER (includes such data as structure length, content, samples per second, and sample size) 

• MMMIDIHEADER (contains all pertinent information about the MIDI) 

• MMMOVIEHEADER 

• MMVIDEOHEADER 


MMIOM GETHEADER - Topics 


Select an item: 
Description 


Returns 

Remarks 

Glossary 


MMIOM IDENTIFYFILE 


MMIOMJDENTIFYFILE Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

An MMIOINFO block is optional for this message. 


MMIOMJDENTIFYFILE Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOMJDENTIFYFILE. 


MMIOM IDENTIFYFILE Parameter - IParaml 


IParaml (LONG) 

An optional pointer to a string, pszF//eName , containing the name of the file to be evaluated. This string must be provided by the 
sender of the message. It should follow the form defined by the mmioOpen function. 


MMIOM IDENTIFYFILE Parameter - IParam2 


IParam2 (LONG) 

An hmm/o file handle must be specified. The lOProc uses this handle to read from the file instead of opening the file again. 


MMIOM IDENTIFYFILE Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The file in the format of, and supported by this lOProc. 

MMIO_ERROR 

The file cannot be supported by this lOProc. 


MMIOMJDENTIFYFILE - Description 


This message attempts to determine if any lOProc can process a file or file element. It does not require that the file be already opened by 
MMIOM_OPEN. 


pmmioinfo (PMMIOINFO) 

An MMIOINFO block is optional for this message. 

usMsg (USHORT) 

Set to MMIOMJDENTIFYFILE. 

IParaml (LONG) 

An optional pointer to a string, pszF/ZeName , containing the name of the file to be evaluated. This string must be provided by the 
sender of the message. It should follow the form defined by the mmioOpen function. 

IParam2 (LONG) 

An hmm/o file handle must be specified. The lOProc uses this handle to read from the file instead of opening the file again, 
rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The file in the format of, and supported by this lOProc. 

MMIO_ERROR 

The file cannot be supported by this lOProc. 


MMIOM IDENTIFYFILE - Remarks 


The lOProc should not depend solely on the extension of the file, but should actually interrogate the file contents, such as header 
information, to ensure support. 

MMIOMJDENTIFYFILE does not require the file to have been opened. The lOProc will normally use mmioOpen and related calls to 
determine if the file is of the correct form. 

Normally MMIOINFO is NULL unless an element given is not valid. 


MMIOMJDENTIFYFILE - Topics 


Select an item: 

Description 

Returns 


Remarks 

Glossary 


MMIOM MULTITRACKREAD 


MMIOMMULTITRACKREAD Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM MULTITRACKREAD Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_MULTITRACKREAD. 


MMIOM MULTITRACKREAD Parameter - IParaml 


IParaml (LONG) 

Pointer to the MMMULTITRACKREAD structure. 


MMIOM MULTITRACKREAD Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM MULTITRACKREAD Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 


MMIO_SUCCESS 

The association is completed successfully. 

MMIO_ERROR 

An error code is returned. 


MMIOMMULTITRACKREAD - Description 


This message is sent to the I/O procedure to request that data be read from one or more tracks from a multiple-track file. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_MULTITRACKREAD. 

IParaml (LONG) 

Pointer to the MMMULTITRACKREAD structure. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The association is completed successfully. 

MMIO_ERROR 

An error code is returned. 


MMIOM MULTITRACKREAD - Topics 

Select an item: 

Description 

Returns 

Glossary 


MMIOM MULTITRACKWRITE 


MMIOM MULTITRACKWRITE Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOMMULTITRACKWRITE Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_MULTITRACKWRITE. 


MMIOM MULTITRACKWRITE Parameter - IParaml 


IParaml (LONG) 

Pointer to the MMMULTITRACKWRITE structure. 


MMIOM MULTITRACKWRITE Parameter - IParam2 


IParam2 (LONG) 
Not used. 


MMIOM MULTITRACKWRITE Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The association is completed successfully. 

MMIO_ERROR 

An error code is returned. 


MMIOM MULTITRACKWRITE - Description 


This message is sent to the I/O procedure to request that data for one or more tracks be written to a multiple-track file. The data for the 
tracks will be interleaved by the I/O procedure. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_MULTITRACKWRITE. 

IParaml (LONG) 

Pointer to the MMMULTITRACKWRITE structure. 

IParam2 (LONG) 

Not used. 

rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The association is completed successfully. 

MMIO_ERROR 

An error code is returned. 


MMIOM MULTITRACKWRITE - Topics 

Select an item: 

Description 

Returns 

Glossary 


MMIOM OPEN 


MMIOM_OPEN Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM_OPEN Parameter - usMsg 

usMsg (USHORT) 

Set to MMIOMJDPEN. 


MMIOM OPEN Parameter - IParaml 


IParaml (LONG) 

The pszF//eName argument of mmioOpen. 


MMIOMOPEN Parameter - IParam2 

IParam2 (LONG) 

This parameter is not used. 


MMIOM OPEN Return Value - rc 


rc (ULONG) 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

The specified file is opened or deleted successfully. Otherwise, either an OS/2 error code or an MMIO error code is 
returned. See Return Codes for a description of the MMIO Manager error codes. 


MMIOMOPEN - Description 

This message is sent to an lOProc by mmioOpen to request that a file be opened or deleted. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_OPEN. 

IParaml (LONG) 

The pszF/'/eName argument of mmioOpen. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

The specified file is opened or deleted successfully. Otherwise, either an OS/2 error code or an MMIO error code is 
returned. See Return Codes for a description of the MMIO Manager error codes. 


MMIOM OPEN - Remarks 


The /D/skOffset field of the MMIOINFO structure is initialized to 0 by mmioOpen before MMIOMJOPEN is called. If this value is incorrect, 
the lOProc must correct it. 

See mmioOpen for a description of the file u/F/ags field of pmmioinfo (which is passed to mmioOpen as u/OpenF/ags ). In particular, if the 
MMIO_DELETE flag is present, the file must be deleted. 


MMIOM_OPEN - Topics 


Select an item: 

Description 

Returns 

Remarks 

Glossary 


MMIOM PASTE 


MMIOM_PASTE Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM PASTE Parameter - usMsg 

usMsg (USHORT) 

Set to MMIOM_PASTE. 


MMIOM PASTE Parameter - IParaml 


IParaml (LONG) 

A pointer to an MMIO_EDIT_PARMS structure. 


MMIOM PASTE Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM PASTE Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 


MMIOMPASTE - Description 


This message is sent to an I/O procedure to request that data from the clipboard be inserted into the file at the position specified. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_PASTE. 

IParaml (LONG) 

A pointer to an MMIO_EDIT_PARMS structure. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 


MMIOM PASTE - Remarks 


Data from the clipboard is inserted into the file at the media position immediately before the u/StartT/me position. (MMIO_EDIT_PARMS 
structure passed in the /Paraml parameter). If the u/Durat/on field of the same structure is not zero, a delete operation is performed for the 
specified range prior to the insertion. After completion of this operation, the media position will be immediately after the pasted data. 

If the u/Durat/on is zero, no deletion of data will take place before the pasting of clipboard data into the file. 


MMIOM_PASTE- Topics 


Select an item: 

Description 

Returns 

Remarks 

Glossary 


MMIOM QUERYHEADERLENGTH 


MMIOMQUERYHEADERLENGTH Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM QUERYHEADERLENGTH Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_QUERYHEADERLENGTH. 


MMIOM QUERYHEADERLENGTH Parameter - 1 Paraml 


IParaml (LONG) 

This parameter is not used. 


MMIOM QUERYHEADERLENGTH Parameter - 1 Param2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM QUERYHEADERLENGTH Return Value - rc 


rc (ULONG) 


Upon successful completion, the size of the header, in bytes, is returned. 
For a failure, 0 is returned. 


MMIOM QUERYHEADERLENGTH - Description 


This message requests the lOProc to return the size of the header for the current file or file element. The file was opened with mmioOpen. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_QUERYHEADERLENGTH. 

IParaml (LONG) 

This parameter is not used. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 


Upon successful completion, the size of the header, in bytes, is returned. 
For a failure, 0 is returned. 


MMIOM QUERYHEADERLENGTH - Remarks 


The lOProc is expected to return the standard presentation format header length when header translation is specified. The following are 
examples of some structures that the preceding parameters might use. These are the standard presentation format header structures. 

• MMIMAGEFIEADER, includes structure length, content, size, color type and other information, including space for a 256-color 
palette. 

■ MMAUDIOPIEADER, includes structure length, content, samples per second, and sample size. 

■ MMMIDIHEADER, contains all pertinent information about the MIDI. 

■ MMMOVIEHEADER contains information about the movie. 

■ MMVIDEOPIEADER contains information about the digital video data. 


MMIOM QUERYHEADERLENGTH - Topics 


Select an item: 

Description 

Returns 

Remarks 

Glossary 


MMIOM QUERYIMAGE 


MMIOMQUERYIMAGE Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM QUERYIMAGE Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_QUERYIMAGE. 


MMIOM QUERYIMAGE Parameter - pulParaml 


pulParaml (PULONG) 

Pointer to a ULONG that will contain the current image index upon return. Image indexes are zero-based. 


MMIOM QUERYIMAGE Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM QUERYIMAGE Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure. 

MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 

MMIOERR_UNSUPPORTED_FUNCTION 

This command is not supported by this image lOProc, so it should be interpreted as having the Oth index image 
selected. 


MMIOMQUERYIMAGE - Description 


This message is sent to an image lOProc to determine the currently selected image index in the image file. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_QUERYIMAGE. 

pulParaml (PULONG) 

Pointer to a ULONG that will contain the current image index upon return. Image indexes are zero-based. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure. 

MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 

MMIOERR_UNSUPPORTED_FUNCTION 

This command is not supported by this image lOProc, so it should be interpreted as having the Oth index image 
selected. 


MMIOM QUERYIMAGE - Related Messages 


MMIOM_QUERYIMAGECOUNT 

MMIOM_SETIMAGE 


MMIOM QUERYIMAGE - Topics 
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MMIOM QUERYIMAGECOUNT 


MMIOMQUERYIMAGECOUNT Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM QUERYIMAGECOUNT Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_QUERYIMAGECOUNT. 


MMIOM QUERYIMAGECOUNT Parameter - pulParaml 


pulParaml (PULONG) 

Pointer to a ULONG that will contain the count of images in this file when the command completes. 


MMIOM QUERYIMAGECOUNT Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM QUERYIMAGECOUNT Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 

MMIOERR_UNSUPPORTED_FUNCTION 

This command is not supported by this image lOProc, so it should be interpreted as supporting only one image. 


MMIOMQUERYIMAGECOUNT - Description 


This message is sent to the lOProc to determine the number of images that are stored in the image file. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_QUERYIMAGECOUNT. 

pulParaml (PULONG) 

Pointer to a ULONG that will contain the count of images in this file when the command completes. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 

MMIOERR_UNSUPPORTED_FUNCTION 

This command is not supported by this image lOProc, so it should be interpreted as supporting only one image. 


MMIOM QUERYIMAGECOUNT - Related Messages 


MMIOM_QUERYIMAGE 

MMIOM_SETIMAGE 


MMIOM QUERYIMAGECOUNT - Topics 
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MMIOM READ 


MMIOM_READ Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM READ Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_READ. 


MMIOM READ Parameter - IParaml 


IParaml (LONG) 

A (PSZ) pointer to the buffer to read to. 


MMIOM READ Parameter - IParam2 


IParam2 (LONG) 

The number of bytes to read. 


MMIOM READ Return Value - rc 


rc (ULONG) 

Returns the number of bytes actually read. Returns OL if no more bytes can be read. 
MMIO_ERROR 

READ was not successful. 


MM I O M R E AD - Description 

This message is sent to an lOProc by mmioRead to request that bytes be read from an open file. Data translation is expected during 
message processing when specified. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_READ. 

IParaml (LONG) 

A (PSZ) pointer to the buffer to read to. 

IParam2 (LONG) 

The number of bytes to read. 

rc (ULONG) 

Returns the number of bytes actually read. Returns OL if no more bytes can be read. 
MMIO_ERROR 

READ was not successful. 


MMIOM_READ- Topics 
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MMIOM REDO 


MMIOM REDO Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOMREDO Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_REDO. 


MMIOM REDO Parameter - IParaml 


IParaml (LONG) 
Not used. 


MMIOM REDO Parameter - IParam2 


IParam2 (LONG) 
Not used. 


MMIOM REDO Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The request to the lOProc was successful. 

MMIO_ERROR 

An error code is returned. 


MMIOM REDO - Description 


This message is sent to an I/O procedure to request the last logical action which was undone by MMIOMJJNDO be redone. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_REDO. 

IParaml (LONG) 

Not used. 

IParam2 (LONG) 

Not used. 

rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The request to the lOProc was successful. 

MMIO_ERROR 

An error code is returned. 


MMIOM_REDO- Topics 


Select an item: 
Description 
Returns 
Glossary 


MMIOM SAVE 


MMIOMSAVE Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM SAVE Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_SAVE. 


MMIOM SAVE Parameter - IParaml 


IParaml (LONG) 

Optional pszFZeName parameter. 


MMIOMSAVE Parameter - IParam2 

IParam2 (LONG) 

This parameter is not used. 


MMIOM SAVE Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The file has been saved. 

MMIO_ERROR 

An error code is returned. 


MMIOM SAVE - Description 


This message is sent to an I/O procedure to request temporary changes in a file be made permanent. A new file name can be supplied to 
save the changes. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


usMsg (USHORT) 

Set to MMIOM_SAVE. 


IParaml (LONG) 

Optional pszFZeName parameter. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 


The file has been saved. 


MMIO_ERROR 

An error code is returned. 


MMIOM_SAVE- Topics 
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MMIOM SEEK 


MMIOM_SEEK Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM_SEEK Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_SEEK. 


MMIOM SEEK Parameter - IParaml 


IParaml (LONG) 

The signed distance (offset) to move, specified as bytes. 


MMIOM SEEK Parameter - IParam2 


IParam2 (LONG) 

Contains one of the following values: 

SEEK_SET 

Moves the file pointer to be /Param/ bytes from the beginning of the file. 

MMIO_SEEK_IFRAME 

This results in a seek to the nearest l-frame preceding the position determined by /Param/ and the other /Param2 
flags. 

SEEK_CUR 

Moves the file position to be /Paraml bytes from the current position. /ParamJ can be positive or negative. 

SEEK_END 

Moves the file position to be /Param / bytes from the end of the file. /Param/ can be positive or negative. 


MMIOM SEEK Return Value - rc 


rc (ULONG) 

Returns the new file position or MMIO_ERROR if the seek was not successful. 


MMIOMSEEK - Description 


This message is sent to an lOProc by mmioSeek to request that the current file position (as maintained by the I/O procedure and stored in 
the /D/skOffset field of the MMIOINFO structure) be moved. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_SEEK. 

IParaml (LONG) 

The signed distance (offset) to move, specified as bytes. 

IParam2 (LONG) 

Contains one of the following values: 

SEEK_SET 

Moves the file pointer to be /Param/ bytes from the beginning of the file. 

MMIO_SEEK_IFRAME 

This results in a seek to the nearest l-frame preceding the position determined by /Param/ and the other /Param2 
flags. 

SEEK_CUR 

Moves the file position to be /Param/ bytes from the current position. /Param/ can be positive or negative. 

SEEK_END 

Moves the file position to be /Param/ bytes from the end of the file. /Param/ can be positive or negative. 

rc (ULONG) 

Returns the new file position or MMIO_ERROR if the seek was not successful. 


MMIOM_SEEK- Topics 
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MMIOM SEEKBYTIME 


MMIOMSEEKBYTIME Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM SEEKBYTIME Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_SEEKBYTIME. 


MMIOM SEEKBYTIME Parameter - IParaml 


IParaml (LONG) 

Contains the signed offset to move, specified in MMTIME. 


MMIOM SEEKBYTIME Parameter - IParam2 


IParam2 (LONG) 

Specifies how the /ParamJ parameter is interpreted: 


SEEK_SET 


Seek to an absolute (time units from the beginning of the file) seek position specified in /Paraml . This is the 


default. 


SEEK_CUR 

Seek to a relative (time units from the current file position) seek position specified in /Param/ . (The value of 
/Param/ can be positive or negative.) 

SEEK_END 

Seek to /Paraml time units from the end of the file. (The value of /Param/ can be positive or negative.) 


MMIOM SEEKBYTIME Return Value - rc 


rc (ULONG) 

Returns the new file position or MMIO_ERROR if the seek was not successful. 


MMIOM SEEKBYTIME - Description 


This message is sent to an I/O procedure by mmioSendMessage and requests the file position (as maintained by the I/O procedure and 
stored in the /DiskOffset field of the MMIOINFO structure) be moved relative to some unit of time understood by the I/O procedure. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_SEEKBYTIME. 

IParaml (LONG) 

Contains the signed offset to move, specified in MMTIME. 

IParam2 (LONG) 

Specifies how the /Param / parameter is interpreted: 

SEEK_SET 

Seek to an absolute (time units from the beginning of the file) seek position specified in /Param/ . This is the 
default. 

SEEK_CUR 

Seek to a relative (time units from the current file position) seek position specified in /Param/ . (The value of 
/Param/ can be positive or negative.) 

SEEK_END 

Seek to /Param/ time units from the end of the file. (The value of /Param/ can be positive or negative.) 

rc (ULONG) 

Returns the new file position or MMIO_ERROR if the seek was not successful. 


MMIOM SEEKBYTIME - Remarks 


Currently, time units are expressed in terms of MMTIME time units (1/3000 of a second). Only some I/O procedures support this. 


MMIOM SEEKBYTIME - Topics 
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MMIOM SET 


MMIOM SET Parameter ■ 

■ pmmioinfo 

pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 



MMIOMSET Parameter ■ 

■ usMsg 

usMsg (USHORT) 

Set to MMIOM_SET. 



MMIOM_SET Parameter ■ 

■ IParaml 

IParaml (LONG) 

Pointer to the MMEXTENDINFO structure. 



MMIOM_SET Parameter ■ 

■ IParam2 

IParam2 (LONG) 

Contains one of the following flags: 



MMIO SET EXTENDEDINFO 


Sets extended information. 


MMIO_QUERY_EXTENDEDINFO_BASE 

Query only the information of MMEXTENDINFO structure. 

MMIO_QUERY_EXTENDEDINFO_ALL 

Query all extended information including the CODEC associated information. 


MMIOM SET Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 
MMIO_SUCCESS 

The set is completed successfully. 

MMIO_ERROR 

An error code is returned. 


MMIOM_SET - Description 


This message is sent to the IQProc to set or query extended file information. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_SET. 

IParaml (LONG) 

Pointer to the MMEXTENDINFO structure. 

IParam2 (LONG) 

Contains one of the following flags: 

MMIO_SET_EXTENDEDINFO 

Sets extended information. 

MMIO_QUERY_EXTENDEDINFO_BASE 

Query only the information of MMEXTENDINFO structure. 

MMIO_QUERY_EXTENDEDINFO_ALL 

Query all extended information including the CODEC associated information. 

rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The set is completed successfully. 

MMIO_ERROR 

An error code is returned. 


MMIOM_SET- Topics 
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MMIOM SETHEADER 


MMIOMSETHEADER Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM SETHEADER Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_SETHEADER. 


MMIOM SETHEADER Parameter - IParaml 


IParaml (LONG) 

Pointer to a header buffer that contains the data to be written by the lOProc to the header of the file element. The application 
responsible for creating and completing the data structure. 


MMIOM SETHEADER Parameter - IParam2 


IParam2 (LONG) 

Length in bytes of the structure supplied in /Paraml . 


MMIOM SETHEADER Return Value - rc 


rc (ULONG) 


Upon successful completion, the number of bytes written is returned. 

For a failure, 0 is returned. 

If the header is invalid, MMIOERR_INVALID_STRUCTURE is set in u/ErrorPet. 


MMIOM SETHEADER - Description 


This message requests the lOProc to use the media-specific information when accepting data about, and writing to, the current file or file 
element. This would include such data as resolution and colors for images, and duration and sample rate for audio. Pleader translation is 
expected to be performed when specified. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_SETHEADER. 


IParaml (LONG) 

Pointer to a header buffer that contains the data to be written by the lOProc to the header of the file element. The application is 
responsible for creating and completing the data structure. 

IParam2 (LONG) 

Length in bytes of the structure supplied in /ParamJ . 


rc (ULONG) 


Upon successful completion, the number of bytes written is returned. 

For a failure, 0 is returned. 

If the header is invalid, MMIOERR_INVALID_STRUCTURE is set in u/ErrorPet. 


MMIOM SETHEADER - Remarks 


This message requires that a valid fimm/o handle be returned from a successful call to MMIOM_OPEN. 

See mmioSetPleader for more information about header information. 

The contents of the header must represent the structure that is expected by the lOProc. It does not represent the way in which data is saved 
by the lOProc because the lOProc might translate the data in some manner. 

Examples of the standard presentation format headers that /Paraml might point to are: 

• MMIMAGEFIEADER, includes structure length, content, size, color type, and other information, including space for a 256-color 


palette. 

MMAUDIOHEADER, includes such data as structure length, content, samples per second, and sample size. 
MMMIDIHEADER, contains all pertinent information about the MIDI. 

MMMOVIEHEADER 

MMVIDEOHEADER 


MMIOM SETHEADER - Topics 
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MMIOM SETIMAGE 


MMIOM_SETIMAGE Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

Pointer to an MMIOINFO data structure. 


MMIOM SETIMAGE Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_SETIMAGE. 


MMIOM SETIMAGE Parameter - ulParaml 


ulParaml (ULONG) 

A ULONG containing the new image index. If the index is less than the count, then an existing image will be addressed. If the index is 
equal to the count, then a new image will be created when mmioSetHeader is called. Indexes greater than the count will generate an 
error. 


MMIOM SETIMAGE Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM SETIMAGE Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure. 

MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 

MMIOERR_UNSUPPORTED_FUNCTION 

The lOProc does not support multiple images. 


MMIOM SETIMAGE - Description 


This message is sent to an image lOProc to select a new image index in the image file. 


pmmioinfo (PMMIOINFO) 

Pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_SETIMAGE. 

ulParaml (ULONG) 

A ULONG containing the new image index. If the index is less than the count, then an existing image will be addressed. If the index is 
equal to the count, then a new image will be created when mmioSetPleader is called. Indexes greater than the count will generate an 
error. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure. 

MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 

MMIOERR_UNSUPPORTED_FUNCTION 

The lOProc does not support multiple images. 


MMIOMSETIMAGE - Related Messages 


MMIOM_QUERYIMAGECOUNT 

MMIOM_QUERYIMAGE 
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MMIOM STATUS 


MMIOM_STATUS Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM_STATUS Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_STATUS. 


MMIOM STATUS Parameter - IParaml 


IParaml (LONG) 

A pointer to an MMIO_STATUS_PARMS structure. 


MMIOM STATUS Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM STATUS Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 

MMIOERR_MISSING_FLAG 

A required flag was not supplied with the command. 

MMIOERRINVALIDJTEMFLAG 

One or more of the item flags specified are invalid for this command. 


MMIOM_STATUS - Description 


This message is used to pass MCI_STATUS messages to an I/O procedure. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_STATUS. 

IParaml (LONG) 

A pointer to an MMIO_STATUS_PARMS structure. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The request was successful. 

MMIO_ERROR 

An error code is returned. 

MMIOERR_MISSING_FLAG 

A required flag was not supplied with the command. 


MMIOERRINVALIDJTEMFLAG 

One or more of the item flags specified are invalid for this command. 


MMIOM STATUS - Remarks 


A TRUE or FALSE value is returned in the u/Return field of the MMIO_STATUS_PARMS structure depending on the status of the item. The 
u/Type field of this structure gives the MCI_FORMAT flag for the returned data when appropriate. 

Item flags for the MCI_STATUS structure are used in the u//tem field of the MMIO_STATUS_PARMS structure. The following flags can be 
used in the u//tem field: 

• MCI_STATUS_CAN_PASTE 

MCI_STATUS_CLIPBOARD 

MCI_STATUS_CAN_REDO 

MCI_STATUS_CAN_UNDO 


MMIOM_STATUS- Topics 
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MMIOM TEMPCHANGE 


MMIOMTEMPCHANGE Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM TEMPCHANGE Parameter - usMsg 


usMsg (USHORT) 


Set to MMIOM_TEMPCHANGE. 


MMIOM TEMPCHANGE Parameter - IParaml 


IParaml (LONG) 

This parameter contains a pointer to a null-terminated string which has the name of a directory where a temporary file should be 
created. 


MMIOM TEMPCHANGE Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM TEMPCHANGE Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The file is recording changes as temporary. 

MMIO_ERROR 

An error code is returned. 


MMIOM TEMPCHANGE - Description 


This message is sent to an I/O procedure to request all subsequent mmioWrite calls to an I/O procedure for a file be treated as temporary 
changes. The changes will not be saved to the file when closed by mmioClose unless an MMIOM_SAVE message is received. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_TEMPCHANGE. 


IParaml (LONG) 

This parameter contains a pointer to a null-terminated string which has the name of a directory where a temporary file should be 
created. 


IParam2 (LONG) 

This parameter is not used. 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The file is recording changes as temporary. 

MMIO_ERROR 

An error code is returned. 


MMIOM TEMPCHANGE - Topics 
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MMIOM UNDO 


MMIOMJJNDO Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOMJJNDO Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOMJJNDO. 


MMIOM UNDO Parameter - IParaml 


IParaml (LONG) 

This parameter is not used. 


MMIOM UNDO Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM UNDO Return Value - rc 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

The request to the lOProc was successful. 

MMIO_ERROR 

An error code is returned. 


MMIOM UNDO - Description 

This message is sent to an I/O procedure to request that the last logical action (MMIOM_DELETE, MMIOM_BEGININSERT, 
MMIOM_ENDINSERT, MMIOMJJNDO, or MMIOMJTEDO) be undone. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOMJJNDO. 

IParaml (LONG) 

This parameter is not used. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return codes indicating success or failure: 

MMIOJ3UCCESS 

The request to the lOProc was successful. 

MMIO_ERROR 

An error code is returned. 


MMIOMJJNDO- Topics 
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MMIOM WINMSG 


MMIOM_WINMSG Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOM_WINMSG Parameter - usMsg 


usMsg (USHORT) 

Set to MMIOM_WINMSG. 


MMIOM WINMSG Parameter - IParaml 


IParaml (LONG) 

A pointer to an MMIO_WINMSG structure. 


MMIOM WINMSG Parameter - IParam2 


IParam2 (LONG) 

This parameter is not used. 


MMIOM WINMSG Return Value - rc 


rc (ULONG) 


Return code indicating success or failure. 


MMIO_SUCCESS 

The request to the lOProc was successful. 

MMIO_ERROR 

An error code is returned. 


MMIOM_WINMSG - Description 


This message allows an application or an MCD to pass PM messages from a window procedure to an I/O procedure. It is currently used to 
pass a WM_DESTROYCLIPBOARD message to an I/O procedure for appropriate action. It is an optional message and may not be 
supported by an I/O procedure, therefore any errors should be ignored by the caller. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 

usMsg (USHORT) 

Set to MMIOM_WINMSG. 

IParaml (LONG) 

A pointer to an MMIO_WINMSG structure. 

IParam2 (LONG) 

This parameter is not used. 

rc (ULONG) 

Return code indicating success or failure. 

MMIO_SUCCESS 

The request to the lOProc was successful. 

MMIO_ERROR 

An error code is returned. 


MMIOM_WINMSG - Topics 
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MMIOM WRITE 


MMIOM_WRITE Parameter - pmmioinfo 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


MMIOMWRITE Parameter - usMsg 

usMsg (USHORT) 

Set to MMIOM_WRITE. 


MMIOM WRITE Parameter - IParaml 


IParaml (LONG) 

A pointer (PCFIAR) to the buffer to write form. 


MM 10 M_W RITE Parameter - IParam2 

IParam2 (LONG) 

The number of bytes to write. 


MMIOM WRITE Return Value - rc 


rc (ULONG) 

Returns the number of bytes actually written or MMIO_ERROR if the write was not successful. 


MMIOM WRITE - Description 


This message is sent to an lOProc by mmioWrite to request that bytes be written to an open file. 


pmmioinfo (PMMIOINFO) 

A pointer to an MMIOINFO data structure. 


usMsg (USHORT) 

Set to MMIOM_WRITE. 

IParaml (LONG) 

A pointer (PCHAR) to the buffer to write form. 

IParam2 (LONG) 

The number of bytes to write. 

rc (ULONG) 

Returns the number of bytes actually written or MMIO_ERROR if the write was not successful. 


MMIOM_WRITE - Topics 
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